shop: a Go API that serves a catalog service over Connect RPC, a products table in Postgres, and a Next.js frontend that calls it through generated, typed React hooks. At the end the whole stack runs on your machine with seeded data, and nothing needs an account.
Forge derives the API from your proto file and the data access from your SQL migrations, so you write one message and get the table, the RPCs, the hooks and the pages. Two sources of truth explains that split. The Forge quick start covers the same ground in prose and goes on to deploy; this guide stays local and shows the output of each step.
Before you begin
- Reliant v1.21.3 or later. Inside Reliant, Forge runs as
reliant forge. A new project pins the Forge it was created with; this guide was run atv1.6.1-0.20261115024114-0ab7c562e817, the Forge embedded in Reliant v1.21.3. Treat that as the minimum. - Go, Node.js and Docker on the machine.
reliant forge project doctorchecks them. - A
forgecommand on yourPATH. The API’s hot-reload config runsforge storage checkbefore each rebuild. If you only havereliant forge, see Troubleshooting.
1
Create the project
--service names the first Go service and --frontend adds a Next.js frontend. --harness none leaves out agent instruction files; drop it to get them.terminal
Output (trimmed)
user.name and user.email, the files are staged but not committed. Set them and commit before you go on.2
Declare a table
--service catalog creates a service with no RPCs and no table. proto/services/catalog/v1/catalog.proto holds only an empty CatalogService. To get a table, add a message marked // forge:entity below the service:proto/services/catalog/v1/catalog.proto
id, created_at and updated_at. Add a database table with a CRUD API and pages covers foreign keys, soft delete and list filters.3
Scaffold what the proto implies
Run bare You now have
reliant forge scaffold. Add --dry-run first to see the plan without writing anything:terminal
Output (trimmed)
db/migrations/<timestamp>_create_products.up.sql, the five RPCs in the proto, handlers in internal/handlers/catalog/handlers_crud.go, hooks such as useListProducts in frontends/web/src/hooks/catalog-service-hooks_gen.ts, and list, view, new and edit pages under frontends/web/src/app/products/. The migration and the handlers are yours from now on; Generated code vs. yours says which files Forge rewrites.4
Run the gate
terminal
Output (trimmed)
generate has nothing left to do after scaffold, which is the point: it proves the tree matches its inputs. Lint runs Go, proto, frontend and migration-safety checks, and took several minutes on a busy machine. Linting explains the lanes.5
Start the stack
terminal
Output (trimmed)
.forge/logs/dev/.6
Check that it works
The API answers health checks, and every RPC refuses a caller with no token, because authentication is fail-closed:The seeded rows are in Postgres:Open
terminal
Output
terminal
Output (trimmed)
http://localhost:3000/products and sign in with the development user declared in idp-steps.yaml (admin@shop.localhost, password Password1!). The page lists the seeded products through useListProducts.7
Stop the stack
terminal
env up starts with your data.What this does not do
- It does not decide who may do what. The CRUD handlers accept any signed-in caller. Access checks and row scoping are code you add with
middleware.GetUser(ctx); the header ofhandlers_crud.goshows where. - The pages are starter code that proves the stack is wired, not a design.
- Nothing is deployed. Environments and deploys and Managed Postgres cover shipping it.
Troubleshooting
api :8085 nothing is listening yet — compilation or startup may still be in progress
api :8085 nothing is listening yet — compilation or startup may still be in progress
Read
.forge/logs/dev/api.log. If it shows /bin/sh: 1: forge: not found and failed to build, error: exit status 127, the hot-reload build could not find a forge command. Install the standalone binary (go install github.com/reliant-labs/forge/cmd/forge@latest), or put a two-line script named forge on your PATH that runs exec reliant forge "$@". Then run reliant forge env down dev and reliant forge env up dev again. If the log shows a slow compile instead, pass --host-ready-timeout 5m.service did not become healthy … compose clickstack
service did not become healthy … compose clickstack
The local telemetry container did not pass its health check in time, which happens on a heavily loaded machine. Run
reliant forge env down dev, then reliant forge env up dev again.Next steps
Add a table with CRUD
Foreign keys, soft delete and list filters on a second entity.
Adding a feature
Custom RPCs, schema changes and tests: the everyday loop.
Project anatomy
Where each generated and owned file lives.
Deploy it
Ship the same project to Reliant hosting.