> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build the UI before the backend with mock mode

> Run your Forge frontend with no API: every RPC answers from generated fixtures, and named scenarios stub the states you design for, such as an empty list.

You will run the `shop` frontend with no API, database or sign-in server behind it, and switch it into a designed state, an empty catalog, from the URL. The pages use the same generated hooks as against the real API, so nothing changes when the backend arrives.

The frontend's transport knows every RPC from the proto. Each answers from the entity fixtures, the same rows [`db seed`](https://docs.reliantlabs.io/guides/forge/seed-realistic-dev-data) writes, or from a default built from the RPC's descriptor, streams and unimplemented RPCs included.

## Before you begin

* A Forge project with a web frontend, such as `shop` from [Add a database table with a CRUD API and pages](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md).
* Forge v1.6 or later. Inside Reliant, run it as `reliant forge`.
* No account and no Docker. Only the frontend runs.

**1. Turn on mock mode for dev**

Set `mock_api` on the frontend's runtime config in the dev environment:

```kcl deploy/kcl/dev/config.k theme={null}
web_config: frontend_config_gen.WebConfig = {
    api_url = "http://localhost:" + str(plugin.resolve_port("shop-dev-api", 8085))
    mock_api = "true"
}
```

| `mock_api` | RPCs | Signed-in user |
| - | - | - |
| `""` (default) | The real API | Your real session |
| `"true"` | Fixtures and generated defaults only | A fixture user, so route guards pass |
| `"hybrid"` | Scenario handlers, everything else to the real API | The same fixture user, in the UI only |

It lands in the frontend's runtime `config.js`, not the bundle. Leave production on `""`.

**2. Start only the frontend**

`--target` scopes the run to one app, so no API, database or containers start:

```bash terminal theme={null}
reliant forge env up dev --target web
```

```text Output (trimmed) theme={null}
│ Frontends
│  ○ web  http://localhost:3000  starting
```

`env up` renders the config, so `http://localhost:3000/config.js` now carries `"MOCK_API": "true"`.

**3. Open a page**

Open `http://localhost:3000/products`. A banner reads `MOCK DATA — backend not connected`, and the list shows 20 fixture products with no request to the API port. Writes persist until you reload. Keep the banner: it is what says a working page is not a working stack.

**4. Scaffold a scenario**

A scenario overrides specific RPCs to put the page in a state you want to design. Create one:

```bash terminal theme={null}
reliant forge scaffold scenario empty-catalog --description "No products yet: the first-run empty state"
```

```text theme={null}
✅ Created frontends/web/src/mocks/scenarios/empty-catalog.ts
```

The file is yours. Override `listProducts` through `mockService`, which types each handler from the service, so a misspelled RPC or field fails `tsc`:

```ts frontends/web/src/mocks/scenarios/empty-catalog.ts theme={null}
import { mockService } from "@reliantlabs/forge-web-runtime/mock-transport";
import { CatalogService } from "@/gen/services/catalog/v1/catalog_pb";
import { defineScenario } from "../scenario-types_gen";

export default defineScenario({
  name: "empty-catalog",
  description: "No products yet: the first-run empty state",
  passthrough: false,
  handlers: {
    ...mockService(CatalogService, {
      listProducts: () => ({ products: [], totalCount: 0 }),
    }),
  },
});
```

To change part of a default instead, patch it: `listProducts: (req, d) => patch(d.listProducts(req), { totalCount: 500 })`. `passthrough: true` sends unmatched RPCs to the real API in `hybrid` mode.

**5. Verify the scenario**

Open `http://localhost:3000/products?scenario=empty-catalog`. The banner is still there, and the table reads:

```text theme={null}
No products found
No records match the current view.
```

Every other RPC still answers from the fixtures. The scenario is read on page load and stays active until a full reload.

**6. Switch back to the real API**

Set `mock_api = ""` (or `"hybrid"` to keep scenarios over the real API) and run `reliant forge env up dev`. Stop the stack with `reliant forge env down dev`.

## What this does not do

* **No domain data in defaults.** Defaults are shape-valid samples (`Product 3`, `user-3@example.com`). What a page must say goes in a scenario or in [`vocab.yaml`](https://docs.reliantlabs.io/guides/forge/seed-realistic-dev-data).
* **No business rules.** Defaults follow `buf.validate` field rules, not CEL rules or your handlers' checks.
* **No production mocks.** `mock_api` is for development; a public demo needs a mock transport you build behind your own switch.

## Troubleshooting

> [accordion] Fixture freshness test fails in task test
>
> The fixtures in `src/mocks/` are stale after a `vocab.yaml` or migration change. Run `reliant forge generate`.

> [accordion] ?scenario= has no effect
>
> The scenario's `name` must match the URL value, and it is read only on a full page load.

## Next steps

> [card] [Seed realistic dev data](https://docs.reliantlabs.io/guides/forge/seed-realistic-dev-data.md)
>
> Give the fixtures and the dev database your domain's words

> [card] [Add a custom RPC](https://docs.reliantlabs.io/guides/forge/add-custom-rpc.md)
>
> Implement the backend the page was built against

> [card] [How forge generate works](https://docs.reliantlabs.io/deep-dives/how-forge-generate-works.md)
>
> Where the fixtures and default modules come from

> [card] [Project anatomy](https://docs.reliantlabs.io/forge/project-anatomy.md)
>
> Which files are generated and which are yours


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.