Make Commands

This page lists common Makefile targets from the repo root. Most day-to-day targets run inside Docker via make. The pre-push gate make local-verification can also run natively on the host — see Local verification.

Start / stop

Command	Purpose
`make start`	Start the stack (`docker compose up`)
`make fresh-start`	Rebuild and start clean (`docker compose up --build --force-recreate --remove-orphans -V`)
`make restart [container=<service>]`	Recreate all containers (`kill` + `start`), or force-recreate one Compose service (example: `make restart container=backend`)
`make kill`	Stop containers
`make clean-docker`	Aggressive Docker cleanup (destructive — can drop volumes)

Stripe

Command	Purpose
`make stripe-setup`	Authenticate the containerized Stripe CLI and auto-set `STRIPE_WEBHOOK_SECRET` in `.env.development`
`make stripe-webhook-secret`	Refresh `STRIPE_WEBHOOK_SECRET` only (skip login)
`make stripe-login`	Log in the Stripe CLI only (no webhook secret write)
`make stripe cmd=...`	Run Stripe CLI in container

Database

Command	Purpose
`make migrate-up`	Run migrations in container
`make seed-up`	Run seeds in container

Operational one-offs (catalog backfills, reconciliation) have no Make target — run via compose + ts-node locally. See Operational Scripts.

Dependencies & build

Command	Purpose
`make deps-install`	Sync deps after git pull or `package.json` edits (host IDE tree + backend/consumer runtime volumes)
`make deps-fix`	Nuclear repair: reset runtime `node_modules` volumes, verify workspace symlinks, restart stack
`make verify-consumer-startup`	Smoke test: cold consumer volumes + start; asserts no tooling `TS2307` errors
`make pnpm-lockfile-frozen-check`	Verify `pnpm-lock.yaml` in frozen mode (advanced; used by `make fresh-start`)
`make pnpm-lockfile-repair`	Regenerate `pnpm-lock.yaml` in an isolated Node container (advanced)
`make build module=<pkg>`	Build one package
`make build-all`	Build workspace packages

Decision tree: git pull / edited package.json / stale deps → make deps-install. Still broken → make deps-fix. Image rebuild → make fresh-start. Deprecated aliases (pnpm-install, pnpm-install-repair, pnpm-lockfile-update) still work and print a notice.

Codegen & quality

Command	Purpose
`make gql-codegen`	GraphQL codegen (stack should be running)
`make local-verification`	Pre-push gate: migrate, lint-deps, lint, build, test, gql-codegen, dirty-tree, production browser-static. Default compose (Docker). Full contract: Local verification
`make local-verification` + native	Host `pnpm` for lint/test/codegen (`REFRACT_EXEC_BACKEND=native` or `EXEC_BACKEND=native`); Docker still required for the prod smoke. Postgres + Redis on localhost; optional `REFRACT_VERIFY_SKIP_INSTALL=1`
`make check-local-verification-backends`	Dry-run smoke: unset → compose, explicit compose/native, invalid rejected
`make test module=<pkg> [path=...]`	Run tests in container
`make test module=<pkg> TEST_SCRIPT=test:debug [path=...]`	Optional debug mode with `--detectOpenHandles --verbose` (backend package)
`make lint module=<pkg> [path=...]`	Lint in container

Use make local-verification as a pre-push gate. Prefer Local verification for backend selection, native prerequisites, and CI relationship. If it passes locally, CI is far more likely to pass on the first run.

Dev proxy Caddyfile

These targets run on the host (they use docker run for Caddy validation, or curl to localhost:8888). They do not replace make test; they guard the unified dev URL routing only.

Command	Purpose
`make validate-dev-proxy`	`caddy validate` on `Caddyfile.dev` via the official Caddy image — no Compose stack required.
`make test-dev-proxy-routing`	Smoke `curl` against :8888 (portal `/__portal/` vs marketing root namespace) — requires `make start`* so `dev-proxy`, portal, and marketing are up.
`make verify-dev-proxy`	Runs both in order (fail-closed gate before pushing dev-proxy changes).

CI: The integration workflow job dev-proxy-verify runs validate-dev-proxy on every pull request. The routing smoke is local-only unless you add a Compose-based CI profile. If backend tests run out of memory locally, increase the heap for a run:

make test module=backend BACKEND_NODE_OPTIONS=--max-old-space-size=8192

Deploy (Railway)

Command	Purpose
`make deploy ENV=staging [SHA=...]`	Deploy via Railway
`make deploy-staging`	Deploy latest to staging
`make deploy-production`	Deploy latest to production

For the full list, run:

make help

Lockfile policy

pnpm-lock.yaml is generated artifact state, not hand-authored code.

Never hand-edit pnpm-lock.yaml.
After merge conflicts in pnpm-lock.yaml, resolve the conflict markers, then run make pnpm-lockfile-repair to regenerate a valid lockfile.
Before pushing or running make fresh-start, run make pnpm-lockfile-frozen-check to fail fast on lockfile integrity problems.
Commit the regenerated pnpm-lock.yaml in the same PR as dependency changes.

What’s next?

Local verification — compose vs native make local-verification.
Configuration system — APP_URL, env vars, dev-proxy routing, and tool swapping.
Architecture overview — the full system map and how each layer connects.
Tooling system — how the tools object is constructed and how loaders work.
Tooling — provider-specific setup for logger, queue, mailer, metrics, and more.
Updating Refract — pull upstream improvements into your project.

Getting Started

Architecture

Frontend

Deployment

Quality

Reference

Start / stop

Stripe

Database

Dependencies & build

Codegen & quality

Dev proxy Caddyfile

Deploy (Railway)

Lockfile policy

What’s next?

​Start / stop

​Stripe

​Database

​Dependencies & build

​Codegen & quality

​Dev proxy Caddyfile

​Deploy (Railway)

​Lockfile policy

​What’s next?

Start / stop

Stripe

Database

Dependencies & build

Codegen & quality

Dev proxy Caddyfile

Deploy (Railway)

Lockfile policy

What’s next?