ai-src

Instrument DOM nodes rendered during Astro, plain React, Vue single-file components, Svelte components, and React Router development with deterministic data-ai-src markers. These attributes encode the relative file path, line, and column that produced each element so tooling (inspectors, agents, IDE extensions, etc.) can jump straight from the browser to source code.

Install

npm install ai-src

The demos/astro/, demos/react/, and demos/react-router/ workspaces in this repo depend on the local package via "ai-src": "file:../..". When using the package in your own project you would install it from npm instead.

Use With Astro

1. Add the plugin to your astro.config.mjs:

   // astro.config.mjs
   import { defineConfig } from "astro/config";
   import react from "@astrojs/react";
   import vue from "@astrojs/vue";
   import { astroAiSrcPlugin, reactAiSrcPlugin, svelteAiSrcPlugin, vueAiSrcPlugin } from "ai-src";
   
   export default defineConfig({
     integrations: [react(), vue()],
     vite: {
       plugins: [astroAiSrcPlugin(), reactAiSrcPlugin(), vueAiSrcPlugin(), svelteAiSrcPlugin()],
     },
   });

2. Run astro dev. Every HTML element in .astro files receives a data-ai-src="relative/path.astro:LINE:COL" attribute.

3. React, Vue, and Svelte islands stay in sync because each framework-specific plugin annotates its host elements and records every component's root location so the Astro-side post-processor can label <astro-island> wrappers with the same marker.

4. Downstream tooling can now read data-ai-src, split on :, and map DOM nodes back to files.

Use With Vue

1. Add the plugin next to your existing Vue tooling in vite.config.ts:

   // vite.config.ts
   import { defineConfig } from "vite";
   import vue from "@vitejs/plugin-vue";
   import { vueAiSrcPlugin } from "ai-src/vue";
   
   export default defineConfig({
     plugins: [vueAiSrcPlugin(), vue()],
   });

2. Run vite dev. Every host element inside .vue templates receives a deterministic data-ai-src="relative/path.vue:LINE:COL" attribute so you can map DOM nodes back to their single-file components. The plugin also records each component's root position so Astro Vue islands inherit the same metadata when combined with astroAiSrcPlugin().

Use With Svelte (Vite or SvelteKit)

1. Add the plugin next to your existing Svelte tooling in vite.config.ts (swap sveltekit() for svelte() if you're not using SvelteKit):

   // vite.config.ts
   import { defineConfig } from 'vite';
   import { sveltekit } from '@sveltejs/kit/vite';
   import { svelteAiSrcPlugin } from 'ai-src/svelte';
   
   export default defineConfig({
     plugins: [svelteAiSrcPlugin(), sveltekit()],
   });

2. Run vite dev (or your SvelteKit npm run dev). Every host element inside .svelte templates receives data-ai-src="relative/path.svelte:LINE:COL" so tooling can hop straight from DOM nodes back to their components.

3. Pass projectRoot if your sources live outside the Vite project root. The plugin uses the root to encode the correct relative path inside each attribute.

4. Pairing this plugin with astroAiSrcPlugin() ensures every Svelte island exposes its recorded root position so the Astro HTML post-processor can tag <astro-island> wrappers with the same metadata.

Use With React (Vite)

1. Register the plugin alongside your existing React tooling inside vite.config.ts:

   // vite.config.ts
   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { reactAiSrcPlugin } from "ai-src/react";
   
   export default defineConfig({
     plugins: [reactAiSrcPlugin(), react()],
   });

2. Run vite dev. Each JSX host element rendered during development receives data-ai-src="relative/path.tsx:LINE:COL", so inspectors can jump from the DOM back to the file that produced it.

3. Pass projectRoot if your repository stores sources outside the Vite root (for example, monorepos). The plugin uses that root to compute the relative file paths encoded in every attribute.

Use With Solid (Vite)

1. Register the plugin next to your existing Solid tooling inside vite.config.ts:

   // vite.config.ts
   import { defineConfig } from "vite";
   import solid from "vite-plugin-solid";
   import { solidAiSrcPlugin } from "ai-src/solid";
   
   export default defineConfig({
     plugins: [solidAiSrcPlugin(), solid()],
   });

2. Run vite dev. Every JSX host element rendered during development receives data-ai-src="relative/path.tsx:LINE:COL", so inspectors can map DOM nodes back to the file that produced them.

3. Pass projectRoot if your repository stores sources outside the Vite root. The plugin uses that root to compute the relative file paths encoded in every attribute.

Use With React Router v7

1. Install the package and its React Router export:

   npm install ai-src

2. Update vite.config.ts to instrument route modules:

   // vite.config.ts
   import { reactRouter } from "@react-router/dev/vite";
   import tailwindcss from "@tailwindcss/vite";
   import { defineConfig } from "vite";
   import { reactRouterAiSrcPlugin } from "ai-src/react-router";
   
   export default defineConfig({
     plugins: [reactRouterAiSrcPlugin(), tailwindcss(), reactRouter()],
   });

3. Every JSX host element that originates from a file under app/routes/ receives:

   • data-ai-src="relative/path.tsx:LINE:COL"
   • data-ai-route-id="route.path" computed from the file name
   • data-ai-route-file="app/routes/..." to map DOM nodes directly back to the route module

   Pass routesDirectories (string or string[]) if your project stores routes somewhere other than app/routes.

Local Playground

This repository ships demo projects under demos/:

• demos/astro/ mirrors the Astro + React/Vue/Svelte integration described above.
• demos/react/ shows how to use the React plugin in a plain Vite app.
• demos/vue/ wires the Vue plugin into a standard Vite starter.
• demos/svelte/ demonstrates the Svelte plugin in a SvelteKit project.
• demos/solid/ demonstrates the Solid plugin on top of vite-plugin-solid.
• demos/react-router/ demonstrates the dedicated React Router plugin and its route metadata attributes.

After installing dependencies at the repo root and inside whichever demo you want to explore (for example, demos/astro/), run the demo's npm run dev to see the instrumentation live.