Skip to main content
You will create 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 at v1.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 doctor checks them.
  • A forge command on your PATH. The API’s hot-reload config runs forge storage check before each rebuild. If you only have reliant 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)
If git has no 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
Field numbers start at 2 because Forge adds 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 reliant forge scaffold. Add --dry-run first to see the plan without writing anything:
terminal
Output (trimmed)
You now have 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
The first run applies the migration, starts Postgres, a local sign-in provider, the API under hot reload, the frontend and a local telemetry stack, and seeds the empty table:
Output (trimmed)
Run from an agent or a script, the command returns with the stack running. Every process logs to .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:
terminal
Output
The seeded rows are in Postgres:
terminal
Output (trimmed)
Open 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
It stops only this project’s processes and containers and keeps the database, so the next 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 of handlers_crud.go shows 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

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.
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.
Forge troubleshooting covers other startup failures.

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.