Skip to content

Developing a react-monorepo

Generation copied each apps/*/.env.example to .env, ran yarn install, formatted the code and made the first commit.

  1. Run the API (a nest-api on port 5000). Its trusted origins and CORS must include every app you run.

  2. Start every app:

    Terminal window
    yarn dev # turbo runs each app's dev server

    landing on 3000, auth on 3001, client on 3002, admin on 3003 (those you generated).

  3. 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.

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.

@scope/types needs packages/types/.env (not created for you):

API_DOC_URL=http://localhost:5000/openapi-json
API_DOC_USER=admin # the API's BASIC_AUTH_USER
API_DOC_PASSWORD=… # the API's BASIC_AUTH_PASS

Then 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.

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.

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.

The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:

  • CLAUDE.md at the root: the monorepo’s commands, which app does what, and the rules (shared code is a package, one baseApi, 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.
SkillShips withWhat it does
add-componentEvery 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-screenEvery 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-pageapp-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-pageapp-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-listenerrealtime

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.