Component Spot ID Toolkit

The Component Spot ID toolkit pairs a TypeScript CLI with a Chrome extension to make it easy to locate UI components during development. The CLI scans .tsx files, assigns stable data-spot-id and data-spot-component attributes to React component roots, and stores the identifiers in a mapping file. The Chrome extension lets you click any element in the browser to instantly copy the component name and spot ID to your clipboard.

CLI usage

Install the package as a dev dependency and run the CLI against the project you want to instrument:

npm install --save-dev @random-gg/component-spot-id
npx component-spot-id --root .

The CLI will:

1. Locate all .tsx files that match the include patterns.
2. Detect React components (function declarations, arrow functions, and memo/forwardRef wrappers).
3. Inject data-spot-id and data-spot-component attributes on the JSX returned from each component.
4. Maintain a .component-spot-ids.json mapping so identifiers remain stable between runs.

Command-line options

| Option | Description | | --- | --- | | --root <path> | Root directory to scan (defaults to the current working directory). | | --pattern <glob ...> | One or more inclusion globs relative to --root (defaults to **/*.tsx). | | --ignore <glob ...> | Globs to exclude (defaults to common build, dist, and node modules folders). | | --mapping <path> | Location of the mapping file relative to the project root (defaults to .component-spot-ids.json). | | --dry-run | Preview changes without writing files. | | --verbose | Log every component that receives an ID. | | --silent | Suppress console output. |

When you add the CLI to another project, consider adding a script to package.json for convenience:

{
  "scripts": {
    "spot-id": "component-spot-id --root ."
  }
}

Running npm run spot-id will now keep component identifiers up to date. Because the package defines a prepare script, a TypeScript build will run automatically after installation so the binary in bin/component-spot-id.js is always ready.

Mapping file

Spot IDs are recorded in .component-spot-ids.json at the project root (configurable via --mapping). Each entry uses the pattern <relativePath>#<ComponentName> so IDs stay consistent even if you re-run the CLI. Removing a component from the codebase and running the CLI again will keep the old ID in the mapping file, ensuring that future reintroductions reuse the same identifier.

Chrome extension

The Chrome extension lives in chrome-extension/ and provides a click-to-copy workflow:

1. Open chrome://extensions, enable Developer mode, and click Load unpacked.
2. Select the tools/component-spot-id/chrome-extension directory.
3. Use the toolbar popup or the keyboard shortcut Ctrl + Shift + Y (⌘ + Shift + Y on macOS) to activate capture mode.
4. Hover over an element to see a highlight, then click to copy ComponentName spot-id=<uuid> to your clipboard.
5. Press Esc to cancel capture mode without copying.

The extension looks for the data-spot-id and data-spot-component attributes generated by the CLI. Once copied, the extension flashes a success banner and resets automatically.

Recommended workflow

1. Run the CLI in your application repository to seed or refresh component spot IDs.
2. Rebuild or reload the app so the rendered DOM includes the new data-spot-* attributes.
3. Load the Chrome extension in developer mode and enable capture mode when you need to locate a UI.
4. Paste the copied component info into your AI assistant (for example Codex CLI) to jump straight to the relevant component source.

Troubleshooting

• If the CLI skips a component, ensure the component returns a JSX element (not a fragment) and that its name starts with an uppercase letter.
• The Chrome extension only sees attributes that reach the rendered DOM. Custom components need to forward data-spot-id and data-spot-component to the element they render.
• When running in CI or environments without internet access, install dependencies from an internal mirror or vendor them in advance so the CLI can build.