vite-plugin-jsx-source-attrs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hansanghyeon
+
+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,130 @@
+# vite-plugin-jsx-source-attrs
+
+Vite React 개발 환경에서 JSX 요소에 소스 위치 정보를 담은 attribute를 주입하기 위한 Babel 플러그인 유틸리티입니다.
+
+여러 Analytics MFE 프로젝트에 반복되어 있던 `@wix/babel-plugin-jsx-source-attrs` 설정과 로컬 Babel 플러그인 구현을 공통 패키지로 분리해, 동일한 동작을 한 곳에서 관리하는 것을 목표로 합니다.
+
+## 기능
+
+- 개발 모드 JSX에 `data-source-location` attribute를 주입합니다.
+- 프로덕션 빌드 또는 비활성화 조건에서는 source attribute를 주입하지 않을 수 있습니다.
+- 기본값에서는 intrinsic JSX 요소(`div`, `span`, `my-element`)만 대상으로 합니다.
+- `componentAttributeName`을 지정하면 사용자 컴포넌트에도 별도 attribute를 주입할 수 있습니다.
+- 파일 경로의 query/hash 제거, Vite 가상 모듈 prefix 제거, OS 경로 구분자 정규화를 제공합니다.
+- 이미 같은 이름의 attribute가 있으면 중복으로 주입하지 않습니다.
+
+## 설치
+
+```bash
+bun add -D vite-plugin-jsx-source-attrs
+```
+
+npm을 사용한다면 다음처럼 설치합니다.
+
+```bash
+npm install -D vite-plugin-jsx-source-attrs
+```
+
+## 사용법
+
+`@vitejs/plugin-react`의 Babel 플러그인 배열에 `jsxSourceAttrs()`를 추가합니다.
+
+```ts
+import react from '@vitejs/plugin-react';
+import { jsxSourceAttrs } from 'vite-plugin-jsx-source-attrs';
+import { defineConfig } from 'vite';
+
+export default defineConfig(({ mode }) => ({
+  plugins: [
+    react({
+      babel: {
+        plugins: [
+          jsxSourceAttrs({
+            enabled: mode === 'development',
+            attributeName: 'data-source-location',
+            componentAttributeName: null,
+          }),
+        ],
+      },
+    }),
+  ],
+}));
+```
+
+입력 JSX가 다음과 같다면,
+
+```tsx
+const view = <div />;
+```
+
+개발 모드에서는 다음처럼 source location이 추가됩니다.
+
+```tsx
+const view = <div data-source-location="src/App.tsx:1:14" />;
+```
+
+## 옵션
+
+| 옵션 | 기본값 | 설명 |
+| --- | --- | --- |
+| `enabled` | `process.env.NODE_ENV !== 'production'` | attribute 주입 여부입니다. boolean 또는 context 기반 함수로 지정할 수 있습니다. |
+| `attributeName` | `data-source-location` | intrinsic JSX 요소에 주입할 attribute 이름입니다. |
+| `componentAttributeName` | `null` | 사용자 컴포넌트에 별도로 주입할 attribute 이름입니다. `null`이면 사용자 컴포넌트에는 주입하지 않습니다. |
+| `root` | `process.cwd()` | 절대 경로를 상대 경로로 바꿀 기준 루트입니다. |
+| `normalizePath` | 내장 정규화 함수 | 파일 경로를 attribute 값에 맞게 정규화하는 함수입니다. |
+
+### enabled 함수 예시
+
+```ts
+jsxSourceAttrs({
+  enabled: ({ filename }) => filename.endsWith('.tsx') && !filename.includes('/node_modules/'),
+});
+```
+
+### 사용자 컴포넌트 attribute 예시
+
+```ts
+jsxSourceAttrs({
+  attributeName: 'data-source-location',
+  componentAttributeName: 'data-component-source-location',
+});
+```
+
+## 경로 정규화
+
+내장 `normalizeSourcePath()`는 다음 처리를 수행합니다.
+
+- `?raw`, `?import`, `#hash` 같은 query/hash 제거
+- Vite 가상 모듈 prefix인 `\0`, `/@id/__x00__`, `/@fs/`, `virtual:` 제거
+- Windows 경로 구분자 `\\`를 `/`로 정규화
+- `root` 하위 절대 경로를 상대 경로로 변환
+
+## 개발
+
+```bash
+bun install
+bun run lint
+bun run typecheck
+bun run test
+bun run build
+```
+
+한 번에 검증하려면 다음 명령을 사용합니다.
+
+```bash
+bun run verify
+```
+
+## 배포
+
+패키지 배포 산출물은 `package.json`의 `files` 필드와 `.npmignore`로 제한합니다. CI는 Bun 기반으로 검증하고, npm Registry와 GitLab Package Registry 배포 경로를 분리합니다.
+
+자세한 내용은 [`docs/publishing.md`](docs/publishing.md)를 참고하세요.
+
+## 마이그레이션
+
+기존 analytics 프로젝트의 로컬 `jsx-source-attrs.js` 복사본 또는 `@wix/babel-plugin-jsx-source-attrs` 직접 사용을 이 패키지로 바꾸는 방법은 [`docs/migration.md`](docs/migration.md)를 참고하세요.
+
+## 라이선스
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,160 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  jsxSourceAttrs: () => jsxSourceAttrs,
+  normalizeSourcePath: () => normalizeSourcePath
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_path2 = __toESM(require("path"), 1);
+var t = __toESM(require("@babel/types"), 1);
+
+// src/normalize.ts
+var import_node_path = __toESM(require("path"), 1);
+var QUERY_OR_HASH_RE = /[?#]/;
+function removeQueryAndHash(filename) {
+  return filename.split(QUERY_OR_HASH_RE, 1)[0] ?? filename;
+}
+function removeViteVirtualPrefix(filename) {
+  return filename.replace(/^\0+/, "").replace(/^\/?@id\/__x00__/, "").replace(/^\/?@fs\//, "/").replace(/^virtual:/, "");
+}
+function toSlash(filename) {
+  return filename.replace(/\\/g, "/");
+}
+function toRelativeFromRoot(filename, root) {
+  const slashFilename = toSlash(filename);
+  const slashRoot = toSlash(root).replace(/\/$/, "");
+  if (!slashRoot) {
+    return slashFilename;
+  }
+  if (slashFilename === slashRoot) {
+    return import_node_path.default.posix.basename(slashFilename);
+  }
+  if (slashFilename.startsWith(`${slashRoot}/`)) {
+    return slashFilename.slice(slashRoot.length + 1);
+  }
+  const relative = toSlash(import_node_path.default.relative(root, filename));
+  if (!relative.startsWith("..") && relative !== "") {
+    return relative;
+  }
+  return slashFilename;
+}
+function normalizeSourcePath(filename, context) {
+  const withoutQuery = removeQueryAndHash(filename);
+  const withoutVirtualPrefix = removeViteVirtualPrefix(withoutQuery);
+  const slashPath = toSlash(withoutVirtualPrefix);
+  return toRelativeFromRoot(slashPath, context.root);
+}
+
+// src/index.ts
+var DEFAULT_ATTRIBUTE_NAME = "data-source-location";
+function resolveOptions(options) {
+  return {
+    enabled: options.enabled ?? process.env.NODE_ENV !== "production",
+    attributeName: options.attributeName ?? DEFAULT_ATTRIBUTE_NAME,
+    componentAttributeName: options.componentAttributeName ?? null,
+    root: import_node_path2.default.resolve(options.root ?? process.cwd()),
+    normalizePath: options.normalizePath ?? normalizeSourcePath
+  };
+}
+function getContext(state, options) {
+  return {
+    filename: state.file.opts.filename ?? "unknown",
+    root: options.root,
+    envName: state.file.opts.envName
+  };
+}
+function shouldInject(state, options) {
+  if (typeof options.enabled === "function") {
+    return options.enabled(getContext(state, options));
+  }
+  return options.enabled;
+}
+function isIntrinsicName(name) {
+  if (!t.isJSXIdentifier(name)) {
+    return false;
+  }
+  return /^[a-z]/.test(name.name) || name.name.includes("-");
+}
+function getTargetAttributeName(name, options) {
+  if (isIntrinsicName(name)) {
+    return options.attributeName;
+  }
+  return options.componentAttributeName;
+}
+function hasAttribute(node, attributeName) {
+  return node.attributes.some((attribute) => {
+    return t.isJSXAttribute(attribute) && t.isJSXIdentifier(attribute.name, { name: attributeName });
+  });
+}
+function createLocationValue(pathToOpeningElement, state, options) {
+  const location = pathToOpeningElement.node.loc?.start;
+  if (!location) {
+    return null;
+  }
+  const context = getContext(state, options);
+  const filename = options.normalizePath(context.filename, {
+    ...context,
+    rawFilename: context.filename
+  });
+  return `${filename}:${location.line}:${location.column + 1}`;
+}
+function jsxSourceAttrs(options = {}) {
+  const resolvedOptions = resolveOptions(options);
+  return {
+    name: "vite-plugin-jsx-source-attrs",
+    visitor: {
+      JSXOpeningElement(pathToOpeningElement, state) {
+        if (!shouldInject(state, resolvedOptions)) {
+          return;
+        }
+        const attributeName = getTargetAttributeName(pathToOpeningElement.node.name, resolvedOptions);
+        if (!attributeName || hasAttribute(pathToOpeningElement.node, attributeName)) {
+          return;
+        }
+        const value = createLocationValue(pathToOpeningElement, state, resolvedOptions);
+        if (!value) {
+          return;
+        }
+        pathToOpeningElement.node.attributes.push(
+          t.jsxAttribute(t.jsxIdentifier(attributeName), t.stringLiteral(value))
+        );
+      }
+    }
+  };
+}
+var index_default = jsxSourceAttrs;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  jsxSourceAttrs,
+  normalizeSourcePath
+});

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+import { PluginObj, PluginPass } from '@babel/core';
+
+interface JsxSourceAttrsContext {
+    /** Babel이 전달한 파일명입니다. */
+    filename: string;
+    /** 경로를 상대화할 기준 루트입니다. */
+    root: string;
+    /** Babel envName입니다. */
+    envName?: string;
+}
+interface NormalizePathContext extends JsxSourceAttrsContext {
+    /** attribute 값 생성을 위해 query/hash를 제거하기 전 원본 파일명입니다. */
+    rawFilename: string;
+}
+interface JsxSourceAttrsOptions {
+    /**
+     * attribute 주입 여부입니다.
+     * 기본값은 `process.env.NODE_ENV !== 'production'`입니다.
+     */
+    enabled?: boolean | ((context: JsxSourceAttrsContext) => boolean);
+    /** intrinsic JSX 요소에 주입할 attribute 이름입니다. */
+    attributeName?: string;
+    /** 사용자 컴포넌트에 주입할 attribute 이름입니다. `null`이면 주입하지 않습니다. */
+    componentAttributeName?: string | null;
+    /** 절대 경로를 상대 경로로 바꿀 기준 루트입니다. */
+    root?: string;
+    /** 파일 경로를 attribute 값에 맞게 정규화하는 함수입니다. */
+    normalizePath?: (filename: string, context: NormalizePathContext) => string;
+}
+
+declare function normalizeSourcePath(filename: string, context: NormalizePathContext): string;
+
+interface JsxSourceAttrsPluginState extends PluginPass {
+    file: PluginPass['file'] & {
+        opts: PluginPass['file']['opts'] & {
+            filename?: string;
+            envName?: string;
+        };
+    };
+}
+/**
+ * Vite의 `@vitejs/plugin-react` Babel 플러그인 배열에 넣어 사용하는 JSX source attribute 플러그인입니다.
+ */
+declare function jsxSourceAttrs(options?: JsxSourceAttrsOptions): PluginObj<JsxSourceAttrsPluginState>;
+
+export { type JsxSourceAttrsContext, type JsxSourceAttrsOptions, type NormalizePathContext, jsxSourceAttrs as default, jsxSourceAttrs, normalizeSourcePath };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { PluginObj, PluginPass } from '@babel/core';
+
+interface JsxSourceAttrsContext {
+    /** Babel이 전달한 파일명입니다. */
+    filename: string;
+    /** 경로를 상대화할 기준 루트입니다. */
+    root: string;
+    /** Babel envName입니다. */
+    envName?: string;
+}
+interface NormalizePathContext extends JsxSourceAttrsContext {
+    /** attribute 값 생성을 위해 query/hash를 제거하기 전 원본 파일명입니다. */
+    rawFilename: string;
+}
+interface JsxSourceAttrsOptions {
+    /**
+     * attribute 주입 여부입니다.
+     * 기본값은 `process.env.NODE_ENV !== 'production'`입니다.
+     */
+    enabled?: boolean | ((context: JsxSourceAttrsContext) => boolean);
+    /** intrinsic JSX 요소에 주입할 attribute 이름입니다. */
+    attributeName?: string;
+    /** 사용자 컴포넌트에 주입할 attribute 이름입니다. `null`이면 주입하지 않습니다. */
+    componentAttributeName?: string | null;
+    /** 절대 경로를 상대 경로로 바꿀 기준 루트입니다. */
+    root?: string;
+    /** 파일 경로를 attribute 값에 맞게 정규화하는 함수입니다. */
+    normalizePath?: (filename: string, context: NormalizePathContext) => string;
+}
+
+declare function normalizeSourcePath(filename: string, context: NormalizePathContext): string;
+
+interface JsxSourceAttrsPluginState extends PluginPass {
+    file: PluginPass['file'] & {
+        opts: PluginPass['file']['opts'] & {
+            filename?: string;
+            envName?: string;
+        };
+    };
+}
+/**
+ * Vite의 `@vitejs/plugin-react` Babel 플러그인 배열에 넣어 사용하는 JSX source attribute 플러그인입니다.
+ */
+declare function jsxSourceAttrs(options?: JsxSourceAttrsOptions): PluginObj<JsxSourceAttrsPluginState>;
+
+export { type JsxSourceAttrsContext, type JsxSourceAttrsOptions, type NormalizePathContext, jsxSourceAttrs as default, jsxSourceAttrs, normalizeSourcePath };

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/index.ts
+import path2 from "path";
+import * as t from "@babel/types";
+
+// src/normalize.ts
+import path from "path";
+var QUERY_OR_HASH_RE = /[?#]/;
+function removeQueryAndHash(filename) {
+  return filename.split(QUERY_OR_HASH_RE, 1)[0] ?? filename;
+}
+function removeViteVirtualPrefix(filename) {
+  return filename.replace(/^\0+/, "").replace(/^\/?@id\/__x00__/, "").replace(/^\/?@fs\//, "/").replace(/^virtual:/, "");
+}
+function toSlash(filename) {
+  return filename.replace(/\\/g, "/");
+}
+function toRelativeFromRoot(filename, root) {
+  const slashFilename = toSlash(filename);
+  const slashRoot = toSlash(root).replace(/\/$/, "");
+  if (!slashRoot) {
+    return slashFilename;
+  }
+  if (slashFilename === slashRoot) {
+    return path.posix.basename(slashFilename);
+  }
+  if (slashFilename.startsWith(`${slashRoot}/`)) {
+    return slashFilename.slice(slashRoot.length + 1);
+  }
+  const relative = toSlash(path.relative(root, filename));
+  if (!relative.startsWith("..") && relative !== "") {
+    return relative;
+  }
+  return slashFilename;
+}
+function normalizeSourcePath(filename, context) {
+  const withoutQuery = removeQueryAndHash(filename);
+  const withoutVirtualPrefix = removeViteVirtualPrefix(withoutQuery);
+  const slashPath = toSlash(withoutVirtualPrefix);
+  return toRelativeFromRoot(slashPath, context.root);
+}
+
+// src/index.ts
+var DEFAULT_ATTRIBUTE_NAME = "data-source-location";
+function resolveOptions(options) {
+  return {
+    enabled: options.enabled ?? process.env.NODE_ENV !== "production",
+    attributeName: options.attributeName ?? DEFAULT_ATTRIBUTE_NAME,
+    componentAttributeName: options.componentAttributeName ?? null,
+    root: path2.resolve(options.root ?? process.cwd()),
+    normalizePath: options.normalizePath ?? normalizeSourcePath
+  };
+}
+function getContext(state, options) {
+  return {
+    filename: state.file.opts.filename ?? "unknown",
+    root: options.root,
+    envName: state.file.opts.envName
+  };
+}
+function shouldInject(state, options) {
+  if (typeof options.enabled === "function") {
+    return options.enabled(getContext(state, options));
+  }
+  return options.enabled;
+}
+function isIntrinsicName(name) {
+  if (!t.isJSXIdentifier(name)) {
+    return false;
+  }
+  return /^[a-z]/.test(name.name) || name.name.includes("-");
+}
+function getTargetAttributeName(name, options) {
+  if (isIntrinsicName(name)) {
+    return options.attributeName;
+  }
+  return options.componentAttributeName;
+}
+function hasAttribute(node, attributeName) {
+  return node.attributes.some((attribute) => {
+    return t.isJSXAttribute(attribute) && t.isJSXIdentifier(attribute.name, { name: attributeName });
+  });
+}
+function createLocationValue(pathToOpeningElement, state, options) {
+  const location = pathToOpeningElement.node.loc?.start;
+  if (!location) {
+    return null;
+  }
+  const context = getContext(state, options);
+  const filename = options.normalizePath(context.filename, {
+    ...context,
+    rawFilename: context.filename
+  });
+  return `${filename}:${location.line}:${location.column + 1}`;
+}
+function jsxSourceAttrs(options = {}) {
+  const resolvedOptions = resolveOptions(options);
+  return {
+    name: "vite-plugin-jsx-source-attrs",
+    visitor: {
+      JSXOpeningElement(pathToOpeningElement, state) {
+        if (!shouldInject(state, resolvedOptions)) {
+          return;
+        }
+        const attributeName = getTargetAttributeName(pathToOpeningElement.node.name, resolvedOptions);
+        if (!attributeName || hasAttribute(pathToOpeningElement.node, attributeName)) {
+          return;
+        }
+        const value = createLocationValue(pathToOpeningElement, state, resolvedOptions);
+        if (!value) {
+          return;
+        }
+        pathToOpeningElement.node.attributes.push(
+          t.jsxAttribute(t.jsxIdentifier(attributeName), t.stringLiteral(value))
+        );
+      }
+    }
+  };
+}
+var index_default = jsxSourceAttrs;
+export {
+  index_default as default,
+  jsxSourceAttrs,
+  normalizeSourcePath
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "vite-plugin-jsx-source-attrs",
+  "version": "0.1.0",
+  "description": "Vite React 개발 환경에서 JSX 요소에 소스 위치 attribute를 주입하는 Babel 플러그인 유틸리티",
+  "type": "module",
+  "license": "MIT",
+  "author": "Hansanghyeon",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@git.hyeon.pro/space/tools/vite-plugin-jsx-source-attrs.git"
+  },
+  "bugs": {
+    "url": "https://git.hyeon.pro/space/tools/vite-plugin-jsx-source-attrs/-/issues"
+  },
+  "homepage": "https://git.hyeon.pro/space/tools/vite-plugin-jsx-source-attrs",
+  "keywords": [
+    "vite",
+    "react",
+    "babel",
+    "jsx",
+    "source-location"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "verify": "bun run lint && bun run typecheck && bun run test && bun run build",
+    "pack:dry": "bun pm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@babel/core": ">=7.20.0"
+  },
+  "dependencies": {
+    "@babel/types": "^7.26.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.0",
+    "@babel/preset-react": "^7.25.9",
+    "@eslint/js": "^9.17.0",
+    "@types/babel__core": "^7.20.5",
+    "@types/bun": "^1.1.14",
+    "eslint": "^9.17.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}