# SpotPatch: Mapping Clicked React Elements to Their JSX Source for Reviewable AI Patches

> SpotPatch is a development-only, local-first Vite plugin that turns rendered React UI into source coordinates, structured prompts, and optionally AI-generated patches. It is a focused tool for engineers who want evidence-based feedback loops without leaving their editor.

**huanglvjing/spotpatch** — Click any React UI element, jump to its exact JSX/TSX source, inspect proven API data flow, and prepare reviewable AI patches. Local-first and development-only.

- Repository: https://github.com/huanglvjing/spotpatch
- Website: https://spotpatch.dev/
- Stars: 134 · Forks: 3
- Language: TypeScript
- License: MIT
- Published: 2026-08-24 · Updated: 2026-08-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/huanglvjing-spotpatch

## The Problem: UI Feedback Without Source Context

When someone reports a styling bug or a data display issue in a React app, the reporter usually sends a screenshot and a vague description. The developer then guesses which component rendered that element, opens the wrong file, and hunts for the relevant line. SpotPatch removes that guesswork by letting you click on the rendered element and jump to its exact JSX or TSX source location. It is built for developers who work on existing Vite or Next.js projects and want to reduce the friction between visual feedback and code changes. It is not a general-purpose debugging tool; it is specifically about turning UI observations into precise, reusable development context.

## How It Works: From Click to Source Coordinates

The core mechanism is a Vite plugin that injects a development-only runtime into your app. When you start the ordinary Vite dev server, a floating 'Select element' button appears in the bottom-right corner, or you press Mod+Shift+S. Clicking that enters a selection mode. You can pick one or more elements, and SpotPatch traces each target back to the source file, line, and column. The README calls this 'UI-to-source, without guesswork'. The plugin places itself before the React plugin in the Vite config, which is how it intercepts component rendering. For each selected target, you can write a separate instruction. The tool then offers several paths: open the exact location in Cursor or VS Code, copy a structured prompt for any coding assistant, or, if AI is configured, run a change in Review mode or Trusted direct mode. The source coordinates are not approximate; they are authorized by the plugin's knowledge of the component tree.

## Setup: One Command for Vite, with Caveats

The quick start requires Node.js 20.19+, React 18.2-18.3, and Vite 5, 6, or 7. From an existing Vite + React project root, run: npx --yes @spotpatch/vite@latest setup. This initializer detects npm or pnpm, installs the matching SpotPatch version, and updates a supported vite.config.*. It also enables the development-only data-flow Beta. If a safe local TypeScript check is discoverable, it exposes the optional Trusted direct mode; otherwise the page starts in Review mode. For manual setup with npm, you run npm install --save-dev @spotpatch/vite@latest and then npx spotpatch-vite init. The generated config looks like this: plugins: [spotPatch({ dataFlow: {}, trustedFastMode: true }), react()]. The initializer supports static config objects and object-returning defineConfig callbacks. Ambiguous dynamic configurations fail without writing the Vite config, so you must integrate manually. On pnpm 11, the recommended setup command is the safest route, or you can install an explicitly trusted exact version, because pnpm's default 24-hour minimumReleaseAge policy may block a fresh release. SpotPatch does not disable that policy globally.

## The Data Flow Beta: Inspecting Proven API Usage

A notable feature is the component data-flow Beta. The README describes it as 'evidence-first': you can inspect proven APIs, parameter keys, consumed response fields, destinations, and current-page unassigned requests without opening DevTools. This is not a static analysis of your code; it is based on actual runtime behavior, so it shows what your components really call and what fields they consume. The setup command enables this Beta by default. For a developer debugging why a UI element shows stale data, this can be more direct than tracing props through multiple components. The feature is labeled Beta, which means its API and behavior may change. The README does not specify how it collects this data or how accurate it is under all conditions, so treat it as a debugging aid rather than a definitive data-flow audit.

## The Guarded AI Path: Review Mode and Trusted Direct

AI integration is optional and explicit. You must configure an OpenAI-compatible provider. The built-in workflow uses bounded tools, an isolated Git worktree, project checks, Diff review, Apply, and conflict-safe Revert. The default is Review mode, where the AI proposes a change and you review the diff before applying. Trusted direct mode is only available when the initializer finds a safe local TypeScript check; it lets the AI apply changes without a review step. This is a deliberate safety design: the tool does not hand arbitrary code execution to the model. The README also mentions an external Agent handoff for Claude Code and Codex. For Codex, you run a connector from the project root, e.g., pnpm exec spotpatch-next connect codex --allow-workspace-write. That connector owns a headless App Server process and reuses your existing Codex authentication. Each 'Send to Agent' action becomes a bounded, source-aware task that starts one Codex turn and reports progress. SpotPatch does not relay approvals or enable sandbox-command networks, which limits what the external agent can do.

## Limitations and When It Is the Wrong Tool

The most obvious limitation is the supported integration matrix. @spotpatch/vite is the only supported public integration. The Next.js adapter is a 0.x public preview and not part of the support matrix, so production Next.js teams should not rely on it. The version requirements are strict: React 18.2-18.3, Vite 5-7, and Node 20.19+. If your project uses React 19 or an older Vite, SpotPatch will not work. The pnpm 11 supply-chain policy can block installation unless you pin an exact version, which may be a hassle for teams that prefer floating versions. The setup command refuses to write the Vite config for ambiguous dynamic configurations, so projects with complex config builders need manual integration. Also, this is a development-only tool; the README states that production builds retain no SpotPatch Runtime, source markers, or local protocol endpoints. That is a feature, but it means you cannot use it to debug a deployed application. For teams that need to inspect production behavior, a different tool is required.

## Alternatives: Browser Extensions and Editor Tools

A common alternative is a browser extension like React DevTools, which lets you inspect the component tree and props of a rendered element. The difference is that React DevTools shows you the component hierarchy and props, but it does not give you a direct jump to the exact source line or column. You still have to open the file manually. Another alternative is the 'Open in Editor' feature in some build tools, which can open a file based on a source map, but that usually requires a special URL or a custom setup. SpotPatch's advantage is that it combines source mapping, data flow inspection, and AI patch generation into one workflow. It also supports multiple targets with independent instructions, up to eight by default. For developers who already use Cursor or VS Code and want a structured prompt for an AI assistant, SpotPatch is more integrated than a generic browser extension. However, if you only need to inspect props and state, React DevTools is simpler and has no version constraints.

## Maintenance, License, and Upgrade Cost

The project is under the MIT license, which is permissive and places few restrictions on use. The repository shows active development, with multiple releases in August 2026, including @spotpatch/vite@1.12.0 and @spotpatch/shared@1.12.0. The shared package suggests that the Vite and Next.js adapters share common logic, but the Next.js adapter is still a preview. Upgrading likely involves running the setup command again or updating the npm package, but the README does not document a specific upgrade path. The data-flow Beta and the external Agent adapters are new enough that their behavior may change between releases. The maintenance cost is low for a single project, but if you depend on the Next.js adapter, expect breaking changes until it reaches 1.x. The project's CI workflow exists, but the README does not describe its coverage. Before adopting, check the changelog for the specific version you plan to use, especially if you rely on the AI workflow.

## Conclusion

Adopt SpotPatch if you work in a Vite 5-7 React project and want to shorten the loop between seeing a UI issue and editing its source, especially when you need structured prompts for AI assistants. Skip it if you need a supported Next.js integration today, since that adapter is a 0.x preview. Before adopting, verify that your Vite config is static or object-returning, that your React version is 18.2-18.3, and that your Node.js is 20.19+. Also check whether your project uses pnpm 11, because its 24-hour minimumReleaseAge policy may block installation unless you pin an exact version.

## FAQ

### What does SpotPatch do when I click a UI element?

It collects bounded DOM, CSS, component information, a confidence value and source coordinates for the selected element, then keeps that context with the target. You can select up to eight targets by default, each with its own request rather than one global note.

### How do I set up SpotPatch in a Vite React project?

Run npx --yes @spotpatch/vite@latest setup from the project root, then start the project with its existing dev command. The initializer detects npm or pnpm, installs the matching adapter, and updates the statically analysable Vite config. Click Select element at the bottom right or press Mod+Shift+S.

### Which React and Vite versions does SpotPatch support?

The supported Vite entry covers React 18.2 through 18.3, Vite 5, 6 and 7, and Node.js 20.19 or newer. React 19 is outside the Vite support commitment, and Chromium is the browser automation baseline.

### Can I use SpotPatch without AI configured?

Yes. Selection, source navigation and prompt copying are core features that require no AI configuration, and the manual integration example sets ai: false explicitly. The built-in change workflow prepares isolated changes and a diff for you to review, and the review decision stays with you.

### Why is SpotPatch component data flow marked beta?

The boundary is evidence-based attribution only, because browsers cannot observe server execution. A value in a rendered component may have come from a server response, a provider, a cache or a distant prop, so attribution means inferring rather than observing.

### Is SpotPatch available for Next.js and Astro?

Astro has a published integration validated against specific fixture versions, and its native templates do not require React. Next.js is a 0.x public preview where installable does not mean fully compatible, and the router, bundler and operating system matrix is unfinished.

## Sources

- [Official documentation](https://spotpatch.dev/)
- [Official README](https://github.com/huanglvjing/spotpatch#readme)
- [Project repository](https://github.com/huanglvjing/spotpatch)
- [Release notes](https://github.com/huanglvjing/spotpatch/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/huanglvjing-spotpatch