swc-plugin-source-tracker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# swc-plugin-source-tracker
+
+SWC plugin that injects `data-source` attributes into JSX DOM elements at compile time.
+
+Each attribute contains the **file path, line number, and column** where the element was defined in source code.
+
+```html
+<!-- Before -->
+<div className="card">
+  <h2>Title</h2>
+  <p>Content</p>
+</div>
+
+<!-- After -->
+<div className="card" data-source="app/page.tsx:12:5">
+  <h2 data-source="app/page.tsx:13:7">Title</h2>
+  <p data-source="app/page.tsx:14:7">Content</p>
+</div>
+```
+
+## Why?
+
+React 19 removed `fiber._debugSource`, breaking all click-to-source tools (react-dev-inspector, LocatorJS, click-to-component, etc.).
+
+This plugin provides a build-time alternative that works with **Next.js 15, 16, Turbopack, and standalone `@swc/core`**.
+
+## Install
+
+```bash
+npm install swc-plugin-source-tracker
+```
+
+## Usage with Next.js
+
+```js
+// next.config.mjs
+import { withSourceTracker } from "swc-plugin-source-tracker";
+
+const nextConfig = {
+  experimental: {
+    swcPlugins: [withSourceTracker()],
+  },
+};
+
+export default nextConfig;
+```
+
+That's it. The plugin auto-detects your Next.js version and selects the compatible WASM binary.
+
+### Dev-only
+
+You probably want this in development only:
+
+```js
+// next.config.mjs
+import { withSourceTracker } from "swc-plugin-source-tracker";
+
+const nextConfig = {
+  experimental: {
+    swcPlugins: [
+      ...(process.env.NODE_ENV === "development" ? [withSourceTracker()] : []),
+    ],
+  },
+};
+
+export default nextConfig;
+```
+
+## Options
+
+```js
+withSourceTracker(
+  // Plugin config (passed to SWC)
+  { attr: "data-source" },    // Custom attribute name (default: "data-source")
+
+  // JS options
+  { version: "v54" },         // Force specific swc_core version: "v35" | "v54"
+);
+```
+
+## Usage with `@swc/core` (standalone)
+
+```js
+import { getWasmPath } from "swc-plugin-source-tracker";
+
+const result = await swc.transform(code, {
+  filename: "src/App.tsx",
+  jsc: {
+    parser: { syntax: "typescript", tsx: true },
+    experimental: {
+      plugins: [[getWasmPath(), {}]],
+    },
+  },
+});
+```
+
+## Compatibility
+
+| WASM | swc_core | Next.js | Bundler |
+|------|----------|---------|---------|
+| v35  | 35.0.0   | 15.x    | Webpack |
+| v54  | 54.0.0   | 16.x    | Turbopack |
+
+`withSourceTracker()` auto-selects the correct version based on your installed Next.js.
+
+## How it works
+
+1. An SWC WASM plugin visits every JSX opening element during compilation
+2. For intrinsic DOM elements (`div`, `span`, `button`, etc.), it injects a `data-source` attribute
+3. The value contains `filename:line:column` resolved from SWC's source map
+4. Custom components (`<MyComponent>`) are skipped — they render DOM elements that get annotated
+
+## Reading source info at runtime
+
+Open DevTools and inspect any element to see its `data-source` attribute, or:
+
+```js
+// Paste in browser console
+document.addEventListener("click", (e) => {
+  const src =
+    e.target.getAttribute("data-source") ||
+    e.target.closest("[data-source]")?.getAttribute("data-source");
+  if (src) console.log(e.target.tagName, "→", src);
+}, true);
+```
+
+## .gitignore
+
+The plugin copies a WASM file to your project root for Turbopack compatibility. Add this to `.gitignore`:
+
+```
+swc_plugin_source_tracker.wasm
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,120 @@
+const path = require("path");
+const fs = require("fs");
+
+const WASM_DIR = path.join(__dirname, "wasm");
+
+/**
+ * swc_core 버전별 WASM 경로 매핑
+ *
+ * Next.js 15.x → swc_common 14.x → swc_core 35
+ * Next.js 16.x → swc_common 18.x → swc_core 54
+ */
+const VERSION_MAP = {
+  v35: path.join(WASM_DIR, "v35.wasm"),
+  v54: path.join(WASM_DIR, "v54.wasm"),
+};
+
+/**
+ * Next.js major 버전 → WASM 버전 매핑
+ */
+const NEXTJS_MAP = {
+  15: "v35",
+  16: "v54",
+};
+
+/**
+ * 설치된 Next.js 버전을 감지한다.
+ */
+function detectNextVersion() {
+  try {
+    const nextPkg = require("next/package.json");
+    return parseInt(nextPkg.version.split(".")[0], 10);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 현재 환경에 맞는 WASM 파일의 절대 경로를 반환한다.
+ *
+ * @param {Object} [options]
+ * @param {"v35"|"v54"} [options.version] - 수동으로 swc_core 버전 지정
+ * @returns {string} WASM 파일의 절대 경로
+ */
+function getWasmPath(options = {}) {
+  let version = options.version;
+
+  if (!version) {
+    const nextMajor = detectNextVersion();
+    if (nextMajor && NEXTJS_MAP[nextMajor]) {
+      version = NEXTJS_MAP[nextMajor];
+    } else {
+      version = "v54";
+    }
+  }
+
+  const wasmPath = VERSION_MAP[version];
+  if (!wasmPath || !fs.existsSync(wasmPath)) {
+    throw new Error(
+      `[swc-plugin-source-tracker] WASM not found for version "${version}". ` +
+        `Available: ${Object.keys(VERSION_MAP).join(", ")}`
+    );
+  }
+
+  return wasmPath;
+}
+
+/**
+ * WASM 파일을 프로젝트 루트에 복사하고 상대 경로를 반환한다.
+ * Turbopack은 node_modules 안의 WASM을 resolve하지 못하므로
+ * 프로젝트 루트에 복사해야 한다.
+ *
+ * @param {string} srcWasmPath - 원본 WASM 절대 경로
+ * @param {string} projectRoot - 프로젝트 루트 (process.cwd())
+ * @returns {string} "./파일명.wasm" 형태의 상대 경로
+ */
+function ensureLocalWasm(srcWasmPath, projectRoot) {
+  const filename = "swc_plugin_source_tracker.wasm";
+  const destPath = path.join(projectRoot, filename);
+
+  // 이미 존재하고 크기가 같으면 복사 생략
+  if (fs.existsSync(destPath)) {
+    const srcStat = fs.statSync(srcWasmPath);
+    const destStat = fs.statSync(destPath);
+    if (srcStat.size === destStat.size) {
+      return "./" + filename;
+    }
+  }
+
+  fs.copyFileSync(srcWasmPath, destPath);
+  return "./" + filename;
+}
+
+/**
+ * next.config.js의 swcPlugins에 바로 넣을 수 있는 튜플을 반환한다.
+ *
+ * WASM 파일을 프로젝트 루트에 자동 복사하여 Turbopack/Webpack 모두에서 동작한다.
+ *
+ * @example
+ * // next.config.mjs
+ * import { withSourceTracker } from "swc-plugin-source-tracker";
+ *
+ * const nextConfig = {
+ *   experimental: {
+ *     swcPlugins: [withSourceTracker()],
+ *   },
+ * };
+ *
+ * @param {Object} [pluginConfig={}] - 플러그인 설정
+ * @param {string} [pluginConfig.attr="data-source"] - DOM에 주입할 속성명
+ * @param {Object} [options]
+ * @param {"v35"|"v54"} [options.version] - swc_core 버전 수동 지정
+ * @returns {[string, Object]} swcPlugins 튜플
+ */
+function withSourceTracker(pluginConfig = {}, options = {}) {
+  const srcWasmPath = getWasmPath(options);
+  const localPath = ensureLocalWasm(srcWasmPath, process.cwd());
+  return [localPath, pluginConfig];
+}
+
+module.exports = { getWasmPath, withSourceTracker, VERSION_MAP, NEXTJS_MAP };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "swc-plugin-source-tracker",
+  "version": "0.1.0",
+  "description": "SWC plugin that injects data-source attributes with file:line:col into JSX DOM elements. Replaces React 19's removed __debugSource. Works with Next.js 15/16 + Turbopack.",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./wasm/v35": "./wasm/v35.wasm",
+    "./wasm/v54": "./wasm/v54.wasm"
+  },
+  "files": [
+    "index.js",
+    "wasm/*.wasm"
+  ],
+  "keywords": [
+    "swc",
+    "swc-plugin",
+    "react",
+    "react-19",
+    "next.js",
+    "turbopack",
+    "debug",
+    "debugSource",
+    "source-tracking",
+    "click-to-source",
+    "jsx",
+    "data-source"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "next": ">=15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  }
+}