> ## 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 a Go and React app with Connect RPC and Postgres

> Create a Go Connect RPC service, a Postgres table and a React frontend with Forge, then run the whole stack on your machine with no account.

You will create `shop`: a Go API that serves a `catalog` service over [Connect RPC](https://connectrpc.com), 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](https://docs.reliantlabs.io/forge/concepts/two-sources-of-truth.md) explains that split. The [Forge quick start](https://docs.reliantlabs.io/forge/quick-start.md) 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](#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.

```bash terminal theme={null}
reliant forge project new shop --service catalog --frontend web --harness none
cd shop
```

```text Output (trimmed) theme={null}
Creating new project 'shop' at shop
  Service: catalog
  Frontend: web
  ✓ project files (1.1s)
  ✓ frontend dependencies — 632 packages installed (1.3s)
  ✓ generate code — 78 files written; compile check skipped (--verify runs it) (3.4s)
  ✓ git repository — initial commit skipped (0.4s)
  ✓ go mod tidy (0.3s)

✅ Project 'shop' created successfully!
```

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:

```protobuf proto/services/catalog/v1/catalog.proto theme={null}
// forge:entity
message Product {
  string name = 2;
  int64 price_cents = 3;
  bool in_stock = 4;
}
```

Field numbers start at 2 because Forge adds `id`, `created_at` and `updated_at`. [Add a database table with a CRUD API and pages](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md) 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:

```bash terminal theme={null}
reliant forge scaffold --dry-run
reliant forge scaffold
```

```text Output (trimmed) theme={null}
── Phase 1: entity births (// forge:entity markers) ─────────────
  📋 would birth services.catalog.v1.Product → table "products" (migration)
        quintet: would inject 5 rpc(s) [CreateProduct GetProduct UpdateProduct DeleteProduct ListProducts] + 10 message(s)
…
✅ Code generation complete — 80 file(s) written, 60 changed (35 new, 25 updated).
── Summary ───────────────────────────────────────────────────────
  entities birthed:    1 (services.catalog.v1.Product → products)
  quintets completed:  1
```

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](https://docs.reliantlabs.io/forge/concepts/generated-vs-yours.md) says which files Forge rewrites.

**4. Run the gate**

```bash terminal theme={null}
reliant forge generate && go build ./... && reliant forge lint --quiet
```

```text Output (trimmed) theme={null}
✅ Code generation complete — 51 file(s) up to date, 0 changed.
⏳ lint: golangci-lint — still running (15s elapsed)
✅ All 29 gating linters passed.
```

`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](https://docs.reliantlabs.io/forge/linting/overview.md) explains the lanes.

**5. Start the stack**

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

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:

```text Output (trimmed) theme={null}
[up] auto-seeded 20 rows across 1 tables (products) — first boot only.
╭─ forge env up · dev ─────────────────────────────────────
│ Host services
│  ● api                 http://localhost:8085  up
│ Frontends
│  ● web                 http://localhost:3000  up
│ Detached — stop with `forge env down dev`
```

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:

```bash terminal theme={null}
curl -s http://localhost:8085/healthz
curl -s -X POST -H 'Content-Type: application/json' -d '{}' \
  http://localhost:8085/services.catalog.v1.CatalogService/ListProducts
```

```text Output theme={null}
ok
{"code":"unauthenticated","message":"missing Authorization header (procedure is not on the unauthenticated allow-list)"}
```

The seeded rows are in Postgres:

```bash terminal theme={null}
reliant forge db query dev "select name, price_cents, in_stock from products limit 3"
```

```text Output (trimmed) theme={null}
name           price_cents  in_stock
sample_name_1  1            true
sample_name_2  2            false
sample_name_3  3            true
```

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**

```bash terminal theme={null}
reliant forge env down dev
```

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](https://docs.reliantlabs.io/forge/environments-and-deploys.md) and [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md) cover shipping it.

## Troubleshooting

> [accordion] 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`.

> [accordion] 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.

[Forge troubleshooting](https://docs.reliantlabs.io/forge/troubleshooting.md) covers other startup failures.

## Next steps

> [card] [Add a table with CRUD](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md)
>
> Foreign keys, soft delete and list filters on a second entity.

> [card] [Adding a feature](https://docs.reliantlabs.io/forge/adding-features.md)
>
> Custom RPCs, schema changes and tests: the everyday loop.

> [card] [Project anatomy](https://docs.reliantlabs.io/forge/project-anatomy.md)
>
> Where each generated and owned file lives.

> [card] [Deploy it](https://docs.reliantlabs.io/forge/quick-start.md#deploy-it)
>
> Ship the same project to Reliant hosting.


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