Modern React Guidance

[ianduvall]

The Chrome team recently shipped Modern Web Guidance — a set of expert-vetted skills that AI coding agents (Claude Code, Copilot CLI, Cursor, etc.) load to write accessible, performant, modern web code. One install command, works across agents, maintained by the team that owns the source of truth.

I'd love to see an equivalent from the React team.

The problem

AI coding agents have become a primary author of React code, and they're systematically biased toward outdated patterns from their training data:

• useState + useEffect for data fetching instead of Suspense + use()
• Manual useMemo / useCallback everywhere — even on projects with React Compiler enabled
• forwardRef in new code (deprecated in React 19; ref is now a normal prop)
• useEffect for things that aren't effects — the classic you might not need an effect footgun
• "use client" by default in RSC-aware frameworks
• Old form patterns instead of <form action> + useActionState + useFormStatus + useOptimistic
• Context.Provider instead of just <Context> (React 19)
• Hand-rolled optimistic UI and transitions instead of useOptimistic / useTransition / useDeferredValue

Every team ends up writing the same CLAUDE.md / .cursorrules / AGENTS.md to patch around this. The guidance is real, stable, and canonical enough that it shouldn't have to be re-derived in every repo.

The proposal

A modern-react-guidance skill pack maintained or blessed by the React team, distributable through the same channels Modern Web Guidance already uses:

• npx skills add facebook/modern-react-guidance (Vercel Agent Skills)
• /plugin install modern-react-guidance (Claude Code, Copilot CLI)
• Plain Markdown drop-in for any agent that reads project rules

Suggested skill categories

Author new components correctly

• use() + Suspense for data fetching where appropriate
• Forms with Actions, useActionState, useFormStatus, useOptimistic
• ref as a normal prop; no forwardRef in new code
• When to reach for useTransition vs useDeferredValue

Don't write effects you don't need

• Codify the "You Might Not Need an Effect" docs as agent guidance: derived state, event handlers, external store subscriptions, data fetching

Trust React Compiler

• Detect Compiler in the project; if present, skip manual useMemo / useCallback
• Coordinate with eslint-plugin-react-hooks / the Compiler linter

Server Components & Actions (framework-agnostic)

• Default to Server Components in RSC-aware projects
• "use client" only when necessary, with a concrete checklist
• Server Actions over ad-hoc API routes for mutations

Modernize legacy React

• Class → function + hooks
• forwardRef → ref-as-prop
• Legacy Context consumers → use(Context)
• Hand-rolled memoization → Compiler-managed

Concurrent UX

• Suspense boundaries for navigation, search, and data
• View Transitions integration

Why the React team specifically

Modern Web Guidance works because Chrome owns the source of truth on what "modern web" means. The React team is the only entity that can authoritatively say "this is the current best practice" without it becoming yet another opinionated third-party lint pack. Without an official version, every framework, lint vendor, and platform team will ship their own — and they'll disagree, and agents will keep writing 2019-era React.

Open questions

• Is this something the team would want to own, bless, or stay out of?
• Versioning: tied to React major versions, or evergreen?

Happy to help draft the first skills if there's appetite — posting here to see if it's worth a formal RFC.

[ianujvarshney]

+1 on this! Also, suggesting a modular approach

This is a fantastic proposal. The amount of time the community wastes rewriting the exact same .cursorrules and CLAUDE.md files just to force AI agents to stop writing 2019-era React is ridiculous. Having an official, canonical source of truth straight from the React team would be a huge win for developer experience.

To build on your open questions, I think the biggest hurdle here is framework fragmentation. "Modern React" looks different depending on the meta-framework you're using (e.g., Server Components in Next.js vs. a standard Vite SPA).

A Suggestion: Modular Skill Packs

If the React team takes this on, it might be best to structure it modularly so agents understand the exact environment they are working in:

• @react-guidance/core: The universal baseline (e.g., using use() instead of useEffect for promises, dropping forwardRef, and letting React Compiler handle memoization).
• @react-guidance/rsc: Specific rules for Server Components, server actions, and the "use client" checklist.
• @react-guidance/spa: Specifics for client-side heavy apps where RSCs aren't available.

Regarding Versioning:

Tying it to major React versions (like modern-react-guidance@19) makes perfect sense. If an agent scans a package.json and sees "react": "^18.2.0", it shouldn't hallucinate a new ref prop or try to use useActionState, which would just break the build. Versioned guidance ensures the AI respects the actual constraints of the project.

I'd love to see this turn into a formal RFC. Count me in if you need a hand drafting the initial markdown rules for the core package!