Skip to content

Developing a react-app

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

  1. Run the API (a nest-api on http://localhost:5000, the default VITE_APP_API_URL). Its trusted origins must include http://localhost:3000.

  2. Start the app:

    Terminal window
    yarn dev # http://localhost:3000
  3. 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.

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

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.

The project’s own task skills carry the full steps for each of these.

  1. Add the route to src/app/router.tsx (lazy-load anything that isn’t the first screen).
  2. Add it to NAV_ITEMS in src/app/nav.tsx if 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.
  3. Put its data calls in src/features/<name>/api.ts with baseApi.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.

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 app’s commands, layout and rules (theme tokens instead of literals, one baseApi, routes named through paths.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.
SkillShips withWhat it does
add-componentEvery 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-screenEvery 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-pageadmin

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

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

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.