Developing a react-monorepo
After generating
Section titled “After generating”Generation copied each apps/*/.env.example to .env, ran yarn install,
formatted the code and made the first commit.
-
Run the API (a nest-api on port 5000). Its trusted origins and CORS must include every app you run.
-
Start every app:
Terminal window yarn dev # turbo runs each app's dev serverlanding on 3000, auth on 3001, client on 3002, admin on 3003 (those you generated).
-
Sign in: open the client at
http://localhost:3002. You’re sent to the auth app’s/login, and after signing in, back to the client.
Scripts
Section titled “Scripts”Root scripts run across every workspace through Turborepo:
| Script | Does |
|---|---|
yarn dev |
Every app’s dev server |
yarn build |
Typecheck and build every app |
yarn typecheck, yarn lint |
Across apps and packages |
yarn format, yarn format:check |
Prettier |
yarn secrets [-e env] |
Each workspace’s .env from Infisical |
One app: yarn workspace client dev, yarn workspace landing build.
API types
Section titled “API types”@scope/types needs packages/types/.env (not created for you):
API_DOC_URL=http://localhost:5000/openapi-jsonAPI_DOC_USER=admin # the API's BASIC_AUTH_USERAPI_DOC_PASSWORD=… # the API's BASIC_AUTH_PASSThen yarn workspace @scope/types gen, and commit src/types/api/: every app
compiles against it. A fresh project ships empty placeholders so it typechecks
before the API exists.
Adding a page
Section titled “Adding a page”The project’s own task skills carry the full steps for each of these.
Add the route to the app’s src/app/router.tsx, and to src/app/nav.tsx if it
belongs in the sidebar (the shell builds the sidebar from that list, not from
the router). Put its data calls in src/features/<name>/api.ts with
baseApi.injectEndpoints.
Adding a package
Section titled “Adding a package”Create packages/<name> with a package.json named @scope/<name> whose
exports points at ./src/index.ts, depend on it from the apps
("@scope/<name>": "workspace:*"), and add a line for it to the Dockerfile’s
dependency stage. If it contains Tailwind classes, add it to the @source lines
in the UI kit’s globals.css.
Building with Claude Code
Section titled “Building with Claude Code”The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:
CLAUDE.mdat the root: the monorepo’s commands, which app does what, and the rules (shared code is a package, onebaseApi, sign-in on the auth app’s origin,VITE_*per app). Claude Code loads it in every session in the project.- Task skills in
.claude/skills/<name>/SKILL.md: step-by-step recipes that point at the template’s own example code. Ask for the task in plain words (“add an endpoint for invoices”) and the matching skill loads.
| Skill | Ships with | What it does |
|---|---|---|
add-component | Every project | Add or restyle a component in the shared UI kit (packages/ui) — variants with cva, the cn helper, theme tokens only, exported from the kit's index. |
add-screen | Every project | Add a screen to one of this monorepo's apps — the route, its data through the shared RTK Query baseApi, loading/empty/error states, forms, page meta and the app's nav entry — built from the shared UI kit. |
add-admin-page | app-admin | Add a page to this monorepo's admin console app (apps/admin) — the route under its RoleRoute, its nav entry, noindex meta, and the API-side check it relies on. |
add-marketing-page | app-landing | Add a public, indexable page to this monorepo's marketing app (apps/landing) — the route, its entry in the SEO route table that drives the sitemap, and its page meta. |
add-realtime-listener | realtime | React to a server-sent Socket.IO event in this monorepo's apps — keep the event names in step with the API, connect once for a signed-in user, join rooms, and update the RTK Query cache when the event arrives. |
A skill that belongs to a feature arrives with it: adding the feature later
with stack add brings its skill and its
CLAUDE.md sections too. Both are yours to edit as the project grows its own
conventions. See Building with Claude Code for
the whole workflow, from a design to a backlog.