feat: add source-map support for editor DOM mapping (#347)

---------

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
Co-authored-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Author: fjakobs

packages/appkit/package.json

@@ -80,6 +80,7 @@
     "express": "4.22.0",
     "get-port": "7.2.0",
     "js-yaml": "4.1.1",
+    "magic-string": "0.30.21",
     "obug": "2.1.1",
     "pg": "8.18.0",
     "picocolors": "1.1.1",

packages/appkit/src/plugins/server/react-source-loc-vite-plugin.ts

@@ -0,0 +1,94 @@
+import path from "node:path";
+import { Lang, parse, type SgNode } from "@ast-grep/napi";
+import MagicString from "magic-string";
+import type { Plugin } from "vite";
+
+const JSX_ELEMENT_MATCHER = {
+  rule: {
+    any: [
+      { kind: "jsx_opening_element" },
+      { kind: "jsx_self_closing_element" },
+    ],
+  },
+};
+
+interface ReactSourceLocPluginOptions {
+  /** Absolute app root used for data-source relative paths (typically `process.cwd()`). */
+  projectRoot: string;
+}
+
+function cleanModuleId(id: string): string {
+  return id.split("?")[0].split("#")[0];
+}
+
+function shouldTransform(id: string): boolean {
+  if (id.includes("\0")) return false;
+  if (id.includes("node_modules")) return false;
+  return /\.[jt]sx$/.test(cleanModuleId(id));
+}
+
+function isNativeJsxTag(name: SgNode): boolean {
+  const kind = name.kind();
+  if (kind === "member_expression") return false;
+  if (kind === "jsx_namespace_name") return false;
+  if (kind === "identifier") {
+    const tagName = name.text();
+    if (!tagName) return false;
+    return /^[a-z]/.test(tagName);
+  }
+  return false;
+}
+
+function hasDataSourceAttribute(node: SgNode): boolean {
+  for (const attr of node.fieldChildren("attribute")) {
+    if (!attr.is("jsx_attribute")) continue;
+    for (const child of attr.children()) {
+      if (child.is("property_identifier") && child.text() === "data-source") {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Injects `data-source="<file>:<line>:<col>"` on native JSX elements so editors
+ * can map DOM nodes back to source locations.
+ */
+export function reactSourceLocPlugin(
+  options: ReactSourceLocPluginOptions,
+): Plugin {
+  const projectRoot = path.resolve(options.projectRoot);
+
+  return {
+    name: "react-source-loc",
+    enforce: "pre",
+    apply: "serve",
+
+    transform(code, id) {
+      if (!shouldTransform(id)) return;
+
+      const cleanId = cleanModuleId(id);
+      const root = parse(Lang.Tsx, code).root();
+      const s = new MagicString(code);
+      const relPath = path.relative(projectRoot, cleanId);
+
+      for (const node of root.findAll(JSX_ELEMENT_MATCHER)) {
+        const name = node.field("name");
+        if (!name || !isNativeJsxTag(name)) continue;
+        if (hasDataSourceAttribute(node)) continue;
+
+        const nodeRange = node.range();
+        const value = `${relPath}:${nodeRange.start.line + 1}:${nodeRange.start.column}`;
+        s.appendLeft(name.range().end.index, ` data-source="${value}"`);
+      }
+
+      if (!s.hasChanged()) return;
+
+      return {
+        code: s.toString(),
+        map: s.generateMap({ hires: true }),
+      };
+    },
+  };
+}

packages/appkit/src/plugins/server/tests/react-source-loc-vite-plugin.test.ts

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { reactSourceLocPlugin } from "../react-source-loc-vite-plugin";
+
+const testDir = path.dirname(fileURLToPath(import.meta.url));
+const clientRoot = path.join(testDir, "client");
+const projectRoot = testDir;
+const moduleId = path.join(clientRoot, "src", "Example.tsx");
+
+interface TestableHooks {
+  transform?: (
+    code: string,
+    id: string,
+  ) =>
+    | { code: string }
+    | string
+    | null
+    | undefined
+    | Promise<{ code: string } | string | null | undefined>;
+}
+
+async function transformSource(
+  code: string,
+  root: string = clientRoot,
+  id: string = moduleId,
+  rootForPaths: string = projectRoot,
+): Promise<string> {
+  const { transform } = reactSourceLocPlugin({
+    projectRoot: rootForPaths,
+  }) as unknown as TestableHooks;
+
+  const result = await transform?.(code, id);
+  if (!result) return code;
+  return typeof result === "string" ? result : result.code;
+}
+
+describe("reactSourceLocPlugin", () => {
+  it("injects data-source on native opening and self-closing tags", async () => {
+    const code = `export function App() {
+  return (
+    <motion.div>
+      <div className="a">
+        <span />
+      </div>
+    </motion.div>
+  );
+}
+`;
+    const output = await transformSource(code);
+    expect(output).toContain('data-source="client/src/Example.tsx:');
+    expect(output).toMatch(/<motion\.div>/);
+    expect(output).toMatch(/<div data-source="[^"]+" className="a">/);
+    expect(output).toMatch(/<span data-source="[^"]+" \/>/);
+    expect(output).not.toContain("motion.div data-source");
+  });
+
+  it("skips components, fragments, namespaced tags, and existing data-source", async () => {
+    const code = `export function App() {
+  return (
+  <>
+    <Foo />
+    <Foo.Bar />
+    <svg:circle />
+    <motion.div data-source="manual" />
+  </>
+  );
+}
+`;
+    const output = await transformSource(code);
+    expect(output).not.toMatch(/<Foo data-source=/);
+    expect(output).not.toMatch(/<Foo\.Bar data-source=/);
+    expect(output).not.toMatch(/<svg:circle data-source=/);
+    expect(output).toContain('<motion.div data-source="manual"');
+    expect(output).not.toMatch(/data-source="[^"]+" data-source=/);
+  });
+
+  it("resolves paths from app root when vite root is the app root", async () => {
+    const appRoot = path.join(testDir, "flat-app");
+    const flatModuleId = path.join(appRoot, "src", "Page.tsx");
+    const code = `export const Page = () => <div className="x" />;`;
+
+    const output = await transformSource(code, appRoot, flatModuleId, appRoot);
+
+    expect(output).toMatch(/<div data-source="src\/Page\.tsx:/);
+    expect(output).not.toMatch(/data-source="[^"]*\.\./);
+  });
+});

packages/appkit/src/plugins/server/vite-dev-server.ts

@@ -8,6 +8,7 @@ import { appKitServingTypesPlugin } from "../../type-generator/serving/vite-plug
 import { appKitTypesPlugin } from "../../type-generator/vite-plugin";
 import { mergeConfigDedup } from "../../utils";
 import { BaseServer } from "./base-server";
+import { reactSourceLocPlugin } from "./react-source-loc-vite-plugin";
 import type { PluginClientConfigs, PluginEndpoints } from "./utils";
 
 const logger = createLogger("server:vite");
@@ -52,6 +53,7 @@ export class ViteDevServer extends BaseServer {
     const react = await import("@vitejs/plugin-react");
 
     const clientRoot = this.findClientRoot();
+    const projectRoot = process.cwd();
 
     const loadedConfig = await loadConfigFromFile(
       {
@@ -81,6 +83,7 @@ export class ViteDevServer extends BaseServer {
       },
       plugins: [
         react.default(),
+        reactSourceLocPlugin({ projectRoot }),
         appKitTypesPlugin(),
         appKitServingTypesPlugin(),
       ],

pnpm-lock.yaml

@@ -6,16 +6,14 @@ import path from 'node:path';
 // https://vite.dev/config/
 export default defineConfig({
   root: __dirname,
-  plugins: [
-    react(),
-    tailwindcss(),
-  ],
+  plugins: [react(), tailwindcss()],
   server: {
     middlewareMode: true,
   },
   build: {
     outDir: path.resolve(__dirname, './dist'),
     emptyOutDir: true,
+    sourcemap: process.env.NODE_ENV === 'development',
   },
   optimizeDeps: {
     include: ['react', 'react-dom', 'react/jsx-dev-runtime', 'react/jsx-runtime', 'recharts'],