Developing a react-app
After generating
Section titled “After generating”Generation copied .env.example to .env, ran yarn install, formatted the
code and made the first commit.
-
Run the API (a nest-api on
http://localhost:5000, the defaultVITE_APP_API_URL). Its trusted origins must includehttp://localhost:3000. -
Start the app:
Terminal window yarn dev # http://localhost:3000 -
Sign in. Opening the app redirects to
/login. Sign up, verify the email (the API sends it through SMTP, or logs it in development, depending on its mail settings), and you land back in the app.
Scripts
Section titled “Scripts”| Script | Does |
|---|---|
yarn dev |
Vite dev server (strict port: a port in use makes it exit rather than move) |
yarn build |
Typecheck the app and the build config, then build to dist/ |
yarn preview |
Serve the built dist/ |
yarn typecheck, yarn lint, yarn format:check |
What CI runs |
yarn gen |
Regenerate API types (below) |
yarn secrets [-e prod] |
Pull .env from Infisical |
API types
Section titled “API types”yarn gen downloads the API’s OpenAPI document from API_DOC_URL (default
http://localhost:5000/openapi-json) with the basic-auth credentials in
API_DOC_USER and API_DOC_PASSWORD (the API’s BASIC_AUTH_USER and
BASIC_AUTH_PASS), then writes types and Zod schemas to
src/shared/types/api/. Run it whenever the API changes, and commit the
result: it’s the contract the app compiles against. 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
src/app/router.tsx(lazy-load anything that isn’t the first screen). - Add it to
NAV_ITEMSinsrc/app/nav.tsxif it belongs in the sidebar: the shell builds the sidebar from that list, not from the router, so a route in one and not the other is unreachable or dead. - Put its data calls in
src/features/<name>/api.tswithbaseApi.injectEndpoints.
Reaching the dev server by another hostname
Section titled “Reaching the dev server by another hostname”Vite only answers localhost by default. Through a tunnel or a wildcard DNS
name, list the hostnames in VITE_APP_ALLOWED_HOSTS (comma-separated), and add
that origin to the API’s trusted origins.
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 app’s commands, layout and rules (theme tokens instead of literals, onebaseApi, routes named throughpaths.ts,VITE_*inlined at build time). 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 this app's UI kit (src/shared/ui) — variants with cva, the cn helper, theme tokens only, exported from the kit's index. |
add-screen | Every project | Add a screen to this React app — the route, its data through RTK Query, loading/empty/error states, forms, page meta and its nav entry — built from the UI kit and theme tokens. |
add-admin-page | admin | Add a page to this app's role-gated admin console under /admin — the route, its nav entry, noindex meta, and the API-side check it relies on. |
add-marketing-page | marketing | Add a public, indexable page to this app's marketing site — the route under MarketingLayout, 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 app — 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.