Skip to content

The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.

8.5 KB
Raw Blame

React Dev Tooling Defaults

When setting up or working on a React project, install three dev-only tools by default unless the user explicitly opts out. They make every coding agent's frontend work measurably faster and the resulting code measurably better.

The three tools

Tool What it does Why it's a default
react-grab Cmd/Ctrl+C on any UI element copies its source location + nearby code + component stack into the clipboard, formatted for an AI agent to act on. Cuts agent edit time ~2× because the agent receives the actual source coordinates instead of guessing from a screenshot. From the author of Million.dev.
react-scan Visually highlights every component render in dev. Detects unnecessary re-renders, slow renders, and tracks render causes. Has a headless react-scan/lite mode for automated perf measurement. Catches re-render regressions the moment they happen, before they ship. Pairs with the perfection ruleset (../perfection/README.md) for Lighthouse 100 work.
react-doctor Static scanner that finds bad React patterns across state & effects, perf, architecture, security, a11y. One-shot npx react-doctor@latest audit + CI GitHub Action + agent-skill installer. Catches AI-generated React anti-patterns deterministically. Run before commit and in CI. Installs itself as a Claude Code / OpenCode / Cursor / Codex skill so the agent learns from each scan.

All three are dev-only (process.env.NODE_ENV === 'development' or import.meta.env.DEV). None ship to production.

Default install for a React project

Run from project root. This is the canonical setup. Skip ONLY if the user says "no extra dev tools" or the project README explicitly forbids them.

# 1. react-grab — adds itself to package.json + entry file with dev gate
npx grab@latest init

# 2. react-doctor — first audit + agent-skill install
npx react-doctor@latest install

# 3. react-scan — adds itself with dev gate
npx react-scan@latest init

The init/install CLIs handle framework detection and gating for you. If the CLI fails or the project uses a non-standard setup, fall back to the manual snippets below.

After install, confirm by reading the diff. Each tool should appear ONLY behind a process.env.NODE_ENV === "development" / import.meta.env.DEV gate.

Manual install (when the CLI does not fit)

Next.js (App Router) — app/layout.tsx

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {process.env.NODE_ENV === "development" && (
          <>
            <Script
              src="//unpkg.com/react-grab/dist/index.global.js"
              crossOrigin="anonymous"
              strategy="beforeInteractive"
            />
            <Script
              src="//unpkg.com/react-scan/dist/auto.global.js"
              crossOrigin="anonymous"
              strategy="beforeInteractive"
            />
          </>
        )}
      </head>
      <body>{children}</body>
    </html>
  );
}

Next.js (Pages Router) — pages/_document.tsx

Same pattern, but the <Script> tags live inside <Head> from next/document and gate on process.env.NODE_ENV === 'development'.

Vite — src/main.tsx (or wherever the entry is)

if (import.meta.env.DEV) {
  void import("react-grab");
  void import("react-scan");
}

Optionally add the Vite plugin for richer displayName data on react-scan:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import reactScan from "vite-plugin-react-scan";

export default defineConfig({
  plugins: [react(), reactScan()],
});

Webpack / CRA — entry file top

if (process.env.NODE_ENV === "development") {
  void import("react-grab");
  void import("react-scan");
}

Remix — app/root.tsx

export default function App() {
  return (
    <html lang="en">
      <head>
        <Meta />
        {process.env.NODE_ENV === "development" && (
          <>
            <script crossOrigin="anonymous" src="//unpkg.com/react-grab/dist/index.global.js" />
            <script crossOrigin="anonymous" src="//unpkg.com/react-scan/dist/auto.global.js" />
          </>
        )}
        <Links />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  );
}

Astro — src/layouts/Layout.astro

---
const isDev = import.meta.env.DEV;
---
<head>
  {isDev && (
    <>
      <script crossorigin="anonymous" src="//unpkg.com/react-grab/dist/index.global.js" is:inline></script>
      <script crossorigin="anonymous" src="//unpkg.com/react-scan/dist/auto.global.js" is:inline></script>
    </>
  )}
</head>

react-doctor — wire the scan, not the bundle

react-doctor is a one-shot CLI plus a CI action, NOT a runtime injection. Wire it in three places:

  1. As an agent skill so your coding agent learns from each scan and avoids the issues next time:

    npx react-doctor@latest install
    

    Detects Claude Code / OpenCode / Cursor / Codex automatically and writes the skill into the right location.

  2. As a local pre-commit / scripted gate:

    # Manual audit
    npx react-doctor@latest
    
    # JSON for scripting / CI
    npx react-doctor@latest --json > .react-doctor-report.json
    
  3. As a CI gate that blocks PRs when the static scan regresses:

    # .github/workflows/react-doctor.yml
    name: React Doctor
    on: [pull_request]
    jobs:
      audit:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: millionco/react-doctor@main
    

Feature flag — opt-out without surgery

The NODE_ENV === "development" gate already keeps these out of production. For temporarily disabling the runtime tools during a dev session (e.g. when profiling without instrumentation overhead), put one env var in front:

// entry file
const enableDevTools =
  process.env.NODE_ENV === "development" &&
  process.env.NEXT_PUBLIC_DISABLE_REACT_DEVTOOLS !== "1";

if (enableDevTools) {
  void import("react-grab");
  void import("react-scan");
}

Then NEXT_PUBLIC_DISABLE_REACT_DEVTOOLS=1 npm run dev skips both without re-editing code.

For Vite use VITE_DISABLE_REACT_DEVTOOLS, for CRA use REACT_APP_DISABLE_REACT_DEVTOOLS. The variable name MUST start with the framework's required prefix or it won't reach the bundle.

When NOT to install these

  • The project is not React. None of these apply to Solid, Svelte, Vue, Qwik, or any non-React framework. Skip silently.
  • The user explicitly said "no extra dev dependencies" or the README forbids them. Respect that.
  • The project ships React 16 or earlier. react-scan and react-doctor target modern React (17+, often 18+). Check package.json first; if the project is on legacy React, skip the runtime tools and only run react-doctor's static scan (it's framework-tolerant).
  • The project is a library, not an app. Libraries have no entry file to inject into; only consumers (apps) should run the runtime tools. The static scan still applies.

Verification

After install, sanity-check that the tools are loaded ONLY in dev:

# 1. Build for production
npm run build && npm run start  # or vite build && vite preview, etc.

# 2. Open the production URL and verify
#    - No react-grab toolbar visible
#    - No react-scan overlay or console output
#    - DOM contains zero <script> tags pointing at unpkg.com/react-grab or unpkg.com/react-scan
curl -s http://localhost:3000 | grep -E 'react-grab|react-scan' && echo "LEAK — fix the gate" || echo "OK"

If any of those leak into production, the dev gate is broken. Fix the gate before declaring done.

Cross-skill references

  • For render performance / Lighthouse 100 work, see ../perfection/react-perf-tooling.md — Playwright + react-scan/lite integration used during automated audits.
  • For browser runtime inspection during an in-flight React bug (rendered state, console, network), load the debugging skill and follow its references/tools/browser-qa.md; React-specific inspection uses the React dev tooling this file sets up.
  • The Phase 0 Design System Gate (in README.md) and this React Dev Tooling Gate are both pre-implementation gates. Run Phase 0 first (design system must exist), then this gate (dev tooling must be installed).

Mantra

Every React project the agent sets up gets these three tools wired with dev-only gates by default. The user opts out, not in.