@docyrus/dom-selector-client

@docyrus/dom-selector-client

A simple CLI that prepares your Vite or Astro project for interactive element selection during development. It injects a lightweight helper script and annotates elements with useful data attributes so external tools can highlight and reference them.

• Adds a dev-only Vite plugin that serves and injects dom-selector-helper.js
• For React projects, adds a Babel plugin to annotate JSX elements with data-component-*
• For Astro/vanilla projects, adds an HTML transform to annotate tags with data-component-*
• Touches only config and adds helper files; no runtime dependency in production

Install

• pnpm: pnpm add -D @docyrus/dom-selector-client
• npm: npm i -D @docyrus/dom-selector-client
• yarn: yarn add -D @docyrus/dom-selector-client

Requires Node 18+.

Quick Start

• npx: npx dom-selector install
• pnpm: pnpm dlx dom-selector install or add it as a dev dep and run dom-selector install

The installer will:

• Detect Astro vs. Vite and framework flavor (React or vanilla)
• Copy dom-selector-helper.js to your project root (if not present)
• Update astro.config.* or vite.config.* to inject a dev-only plugin that includes the helper
• For React projects, copy babel-plugin-component-annotate.ts to your project root and register a Babel transform in Vite to add data-component-name and data-component-path attributes to JSX elements during dev

No changes are made if your config is already set up.

What It Adds

• Dev-only Vite plugin: injects <script type="module" src="/dom-selector-helper.js"></script> into HTML and serves the file from the project root
• React: Babel plugin that annotates all JSX opening elements with:
  • data-component-name: The element/component name
  • data-component-path: Relative file path with line:column (e.g. src/App.tsx:12:5)
• Astro/vanilla: A Vite transform that annotates HTML tags (outside frontmatter/script/style blocks) with the same attributes

Annotations are added only in development. The helper and plugins are inert in production builds.

Using The Helper

The injected dom-selector-helper.js listens for postMessage events:

• Enable: window.postMessage({ type: 'DOCY_SELECTOR', action: 'enable' }, '*')
• Disable: window.postMessage({ type: 'DOCY_SELECTOR', action: 'disable' }, '*')

When enabled, hovering highlights elements, and clicking sends a message to window.parent:

• { type: 'DOCY_SELECTOR', action: 'elementSelected', payload: { rect, componentName, componentPath, tagName, className, hasTextContent, textContent, src } }

This is designed to work inside iframes or dev UIs that consume the selection signal.

Files Touched

• Project root:
  • dom-selector-helper.js (copied if missing)
  • babel-plugin-component-annotate.ts (React projects, copied if missing)
• Config:
  • astro.config.* or vite.config.* updated to register dev-only plugins

You can remove these changes by deleting the two files and reverting the plugin additions in your config.

Notes

• React requires @babel/core for the inline transform. If it’s not found, the installer will warn you to install it: npm i -D @babel/core.
• Vue support: the helper is injected, but element annotation is not yet implemented for Vue components.

CLI

• dom-selector install
  • Options: -d, --directory <dir> target project directory (defaults to CWD)

License

MIT