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 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
shopfrom Add a database table with a CRUD API and pages. - 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:deploy/kcl/dev/config.k
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:terminal
Output (trimmed)
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:The file is yours. Override To change part of a default instead, patch it:
terminal
listProducts through mockService, which types each handler from the service, so a misspelled RPC or field fails tsc:frontends/web/src/mocks/scenarios/empty-catalog.ts
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 Every other RPC still answers from the fixtures. The scenario is read on page load and stays active until a full reload.
http://localhost:3000/products?scenario=empty-catalog. The banner is still there, and the table reads: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 invocab.yaml. - No business rules. Defaults follow
buf.validatefield rules, not CEL rules or your handlers’ checks. - No production mocks.
mock_apiis for development; a public demo needs a mock transport you build behind your own switch.
Troubleshooting
Fixture freshness test fails in task test
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.?scenario= has no effect
?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
Seed realistic dev data
Give the fixtures and the dev database your domain’s words
Add a custom RPC
Implement the backend the page was built against
How forge generate works
Where the fixtures and default modules come from
Project anatomy
Which files are generated and which are yours