Instruction file imported from CarmineTesta/ia-foundaments (.github/instructions/typescript-react.instructions.md). Copyright stays with the author.

TypeScript + React conventions

Applies to React modules identified by presence of react in the module's package.json and by the module being declared with framework: react-* in project-profile.yaml under tech_stacks.

Build & test

• Package manager: check package.json of the touched module and use the declared one (npm / pnpm / yarn / bun). Never mix.
• Bundler: use the one already configured (Vite, Next, Rspack, …). Do not introduce a second bundler.
• Lint: respect the ESLint config at the module root. Do not add plugins without approval (§14 stop-and-ask on tooling changes).
• Tests: use the test runner declared in tech_stacks.<module>.test_runner of the profile (Vitest, Jest, …) with the testing library already present (React Testing Library, …).

Components

• One component per file. Named exports, not default exports.
• Props types via interface when public; type for local shapes.
• Prefer function components + hooks. No class components.
• Do not add a component library (MUI, Chakra, Radix, …) unless one is already present in the module.

State & data

• Local state: useState / useReducer.
• Server state: use the client already configured in the module (React Query, SWR, Apollo, fetch wrappers, …).
• Global state: only if already present. Adding Redux / Zustand / Jotai is a §14 stop-and-ask gate.

Routing

• Use the router already installed (React Router, TanStack Router, …). Do not swap routers.

Do NOT

• Do not commit generated OpenAPI clients unless the module already tracks them.
• Do not add polyfills for browsers outside the module's declared support matrix.
• Do not disable ESLint rules inline without a comment explaining why.
• Do not upgrade React or the bundler across a major version without ADR (§4 rimando + §14 stop-and-ask).