What it isAlways-on coding rules. GitHub Copilot applies them to files matching **/*.tsx,**/*.jsx; the Claude Code version is a path-scoped rule generated from the same file. Why use instructions →
Install
This repository (recommended)
Adds .github/instructions/react.instructions.md — commit it so everyone's Copilot follows the same rules.
Nothing to invoke — edit a matching file and Copilot picks the rules up. Adjust applyTo if your repository layout differs.
This repository (recommended)
Adds .claude/rules/react.md — commit it. Claude loads it when it reads a matching file.
npx -y github:AGCO-Global/org-skills add instructions react --tool claude
Just for me, every repository
Save it in your user profile instead.
npx -y github:AGCO-Global/org-skills add instructions react --tool claude --user
Use it
Nothing to invoke. Adjust the paths globs if your repository layout differs.
Commands run in your repository folder and need Node.js 20+. They use your normal git sign-in to GitHub, so they work while the repository is private. Run npx -y github:AGCO-Global/org-skills list to see everything available.
Settings
name: "React"
description: "Always-on rules for writing and editing React web components and hooks in TypeScript."
applyTo: "**/*.tsx,**/*.jsx"
Instructions Copilot follows
React rules (web)
Scope: these rules are for React on the web. If package.json depends on react-native or expo, ignore this file — the React Native instructions apply instead. In a monorepo with both, narrow applyTo to the web app (for example "apps/web/**/*.tsx").
Follow the existing project conventions first; these rules apply to new and changed code. They are the always-on minimum — for a whole component, feature or refactor, use the react-development skill, and react-architecture when the question is where code should live.
Components
Use function declarations with named exports, one component per file. No React.FC, no default exports except framework route files.
Derive values during render instead of copying props or state into new state. Duplicated state that must be kept in sync is the most common React bug.
Render every state explicitly: loading, empty, error and success. Returning null for an error hides failures from users and from monitoring.
Use stable ids for key. Index keys on a list that reorders or filters corrupt component state.
In Next.js default to Server Components; add "use client" only at the leaf that needs state, effects, browser APIs or event handlers. A client boundary ships its whole import graph.
Hooks, effects and purity
Keep components and hooks pure: no mutation of props, state or refs during render, no ref.current reads in render. StrictMode and the React Compiler both depend on it, and the compiler silently skips impure components.
Call hooks unconditionally at the top level of a component or custom hook.
Use useEffect only to sync with something outside React (browser API, widget, socket, timer), one concern per effect, with a cleanup. Deriving data, resetting state or reacting to an event never needs one — derive in render, use key, or do it in the handler.
Never silence react-hooks/exhaustive-deps; restructure instead. Suppressed deps produce stale closures that fail only in production.
Pass ref as an ordinary prop (React 19+); do not add forwardRef to new code.
Data and state
Fetch server data with TanStack Query, a route loader or a Server Component — never fetch inside useEffect. You get caching, deduplication, cancellation and no race conditions.
Keep query keys in a per-feature factory (orderKeys.list(filters)) so invalidation cannot drift from the queries.
Keep state as local as possible and put shareable UI state (filters, tabs, pagination) in the URL so links and the back button work.
Use context for rarely changing values (theme, session, locale), not for fast-changing state: every consumer re-renders.
Do not add useMemo, useCallback or memo by default. With the React Compiler on they are usually redundant; without evidence from the Profiler they are noise. Diagnose slowness with the react-performance skill.
Resilience and accessibility
Give every route segment an error boundary with a retry and a <Suspense> fallback sized like the content it replaces, so a failed or slow region cannot blank the page or shift the layout.
Use semantic elements: <button> for actions, <a href> for navigation. A clickable <div> is not keyboard operable.
Label every input visibly and give icon-only buttons an aria-label; keep focus visible. Target WCAG 2.2 AA.
Safety
Treat NEXT_PUBLIC_* and VITE_* values as public — everything in the bundle ships to the browser. Import server-only in modules touching secrets, databases or internal APIs so they cannot be pulled into a client bundle.
Validate and authorise inside every Server Action or route action: it is a public endpoint whatever the UI does.
Browser-security rules — HTML sinks including dangerouslySetInnerHTML, URL schemes, CSP, CSRF and token storage — are in frontend-security.instructions.md and are not repeated here.
Types and tests
Keep TypeScript strict; no any, no ! to silence an error — use unknown and narrow. Parse untrusted JSON with a schema.
Test behaviour with React Testing Library, querying by role and label, and fake the network with MSW rather than mocking your own hooks. For writing or fixing tests use the react-testing skill.
Before opening a pull request, use frontend-code-review.
---
name: "React"
description: "Always-on rules for writing and editing React web components and hooks in TypeScript."
applyTo: "**/*.tsx,**/*.jsx"
---
# React rules (web)
> Scope: these rules are for React on the web. If `package.json` depends on `react-native` or `expo`, ignore this file — the React Native instructions apply instead. In a monorepo with both, narrow `applyTo` to the web app (for example `"apps/web/**/*.tsx"`).
Follow the existing project conventions first; these rules apply to new and changed code. They are the always-on minimum — for a whole component, feature or refactor, use the `react-development` skill, and `react-architecture` when the question is where code should live.
## Components
- Use function declarations with named exports, one component per file. No `React.FC`, no default exports except framework route files.
- Derive values during render instead of copying props or state into new state. Duplicated state that must be kept in sync is the most common React bug.
- Render every state explicitly: loading, empty, error and success. Returning `null` for an error hides failures from users and from monitoring.
- Use stable ids for `key`. Index keys on a list that reorders or filters corrupt component state.
- In Next.js default to Server Components; add `"use client"` only at the leaf that needs state, effects, browser APIs or event handlers. A client boundary ships its whole import graph.
## Hooks, effects and purity
- Keep components and hooks pure: no mutation of props, state or refs during render, no `ref.current` reads in render. StrictMode and the React Compiler both depend on it, and the compiler silently skips impure components.
- Call hooks unconditionally at the top level of a component or custom hook.
- Use `useEffect` only to sync with something outside React (browser API, widget, socket, timer), one concern per effect, with a cleanup. Deriving data, resetting state or reacting to an event never needs one — derive in render, use `key`, or do it in the handler.
- Never silence `react-hooks/exhaustive-deps`; restructure instead. Suppressed deps produce stale closures that fail only in production.
- Pass `ref` as an ordinary prop (React 19+); do not add `forwardRef` to new code.
## Data and state
- Fetch server data with TanStack Query, a route loader or a Server Component — never `fetch` inside `useEffect`. You get caching, deduplication, cancellation and no race conditions.
- Keep query keys in a per-feature factory (`orderKeys.list(filters)`) so invalidation cannot drift from the queries.
- Keep state as local as possible and put shareable UI state (filters, tabs, pagination) in the URL so links and the back button work.
- Use context for rarely changing values (theme, session, locale), not for fast-changing state: every consumer re-renders.
- Do not add `useMemo`, `useCallback` or `memo` by default. With the React Compiler on they are usually redundant; without evidence from the Profiler they are noise. Diagnose slowness with the `react-performance` skill.
## Resilience and accessibility
- Give every route segment an error boundary with a retry and a `<Suspense>` fallback sized like the content it replaces, so a failed or slow region cannot blank the page or shift the layout.
- Use semantic elements: `<button>` for actions, `<a href>` for navigation. A clickable `<div>` is not keyboard operable.
- Label every input visibly and give icon-only buttons an `aria-label`; keep focus visible. Target WCAG 2.2 AA.
## Safety
- Treat `NEXT_PUBLIC_*` and `VITE_*` values as public — everything in the bundle ships to the browser. Import `server-only` in modules touching secrets, databases or internal APIs so they cannot be pulled into a client bundle.
- Validate and authorise inside every Server Action or route `action`: it is a public endpoint whatever the UI does.
- Browser-security rules — HTML sinks including `dangerouslySetInnerHTML`, URL schemes, CSP, CSRF and token storage — are in `frontend-security.instructions.md` and are not repeated here.
## Types and tests
- Keep TypeScript `strict`; no `any`, no `!` to silence an error — use `unknown` and narrow. Parse untrusted JSON with a schema.
- Test behaviour with React Testing Library, querying by role and label, and fake the network with MSW rather than mocking your own hooks. For writing or fixing tests use the `react-testing` skill.
- Before opening a pull request, use `frontend-code-review`.
---
paths:
- "**/*.tsx"
- "**/*.jsx"
---
<!-- React — generated from instructions/frontend/react/react.instructions.md for Claude Code. Edit that file, not this one. -->
# React rules (web)
> Scope: these rules are for React on the web. If `package.json` depends on `react-native` or `expo`, ignore this file — the React Native instructions apply instead. In a monorepo with both, narrow `applyTo` to the web app (for example `"apps/web/**/*.tsx"`).
Follow the existing project conventions first; these rules apply to new and changed code. They are the always-on minimum — for a whole component, feature or refactor, use the `react-development` skill, and `react-architecture` when the question is where code should live.
## Components
- Use function declarations with named exports, one component per file. No `React.FC`, no default exports except framework route files.
- Derive values during render instead of copying props or state into new state. Duplicated state that must be kept in sync is the most common React bug.
- Render every state explicitly: loading, empty, error and success. Returning `null` for an error hides failures from users and from monitoring.
- Use stable ids for `key`. Index keys on a list that reorders or filters corrupt component state.
- In Next.js default to Server Components; add `"use client"` only at the leaf that needs state, effects, browser APIs or event handlers. A client boundary ships its whole import graph.
## Hooks, effects and purity
- Keep components and hooks pure: no mutation of props, state or refs during render, no `ref.current` reads in render. StrictMode and the React Compiler both depend on it, and the compiler silently skips impure components.
- Call hooks unconditionally at the top level of a component or custom hook.
- Use `useEffect` only to sync with something outside React (browser API, widget, socket, timer), one concern per effect, with a cleanup. Deriving data, resetting state or reacting to an event never needs one — derive in render, use `key`, or do it in the handler.
- Never silence `react-hooks/exhaustive-deps`; restructure instead. Suppressed deps produce stale closures that fail only in production.
- Pass `ref` as an ordinary prop (React 19+); do not add `forwardRef` to new code.
## Data and state
- Fetch server data with TanStack Query, a route loader or a Server Component — never `fetch` inside `useEffect`. You get caching, deduplication, cancellation and no race conditions.
- Keep query keys in a per-feature factory (`orderKeys.list(filters)`) so invalidation cannot drift from the queries.
- Keep state as local as possible and put shareable UI state (filters, tabs, pagination) in the URL so links and the back button work.
- Use context for rarely changing values (theme, session, locale), not for fast-changing state: every consumer re-renders.
- Do not add `useMemo`, `useCallback` or `memo` by default. With the React Compiler on they are usually redundant; without evidence from the Profiler they are noise. Diagnose slowness with the `react-performance` skill.
## Resilience and accessibility
- Give every route segment an error boundary with a retry and a `<Suspense>` fallback sized like the content it replaces, so a failed or slow region cannot blank the page or shift the layout.
- Use semantic elements: `<button>` for actions, `<a href>` for navigation. A clickable `<div>` is not keyboard operable.
- Label every input visibly and give icon-only buttons an `aria-label`; keep focus visible. Target WCAG 2.2 AA.
## Safety
- Treat `NEXT_PUBLIC_*` and `VITE_*` values as public — everything in the bundle ships to the browser. Import `server-only` in modules touching secrets, databases or internal APIs so they cannot be pulled into a client bundle.
- Validate and authorise inside every Server Action or route `action`: it is a public endpoint whatever the UI does.
- Browser-security rules — HTML sinks including `dangerouslySetInnerHTML`, URL schemes, CSP, CSRF and token storage — are in `frontend-security.instructions.md` and are not repeated here.
## Types and tests
- Keep TypeScript `strict`; no `any`, no `!` to silence an error — use `unknown` and narrow. Parse untrusted JSON with a schema.
- Test behaviour with React Testing Library, querying by role and label, and fake the network with MSW rather than mocking your own hooks. For writing or fixing tests use the `react-testing` skill.
- Before opening a pull request, use `frontend-code-review`.