vite-plugin-jsx-source-attrs

Vite React 개발 환경에서 JSX 요소에 소스 위치 정보를 담은 attribute를 주입하기 위한 Vite 플러그인과 Babel 플러그인 유틸리티입니다.

여러 Analytics MFE 프로젝트에 반복되어 있던 @wix/babel-plugin-jsx-source-attrs 설정과 로컬 Babel 플러그인 구현을 공통 패키지로 분리해, 동일한 동작을 한 곳에서 관리하는 것을 목표로 합니다.

기능

• 개발 모드 JSX에 data-source-location attribute를 주입합니다.
• 프로덕션 빌드 또는 비활성화 조건에서는 source attribute를 주입하지 않을 수 있습니다.
• 기본값에서는 intrinsic JSX 요소(div, span, my-element)에 data-source-location을, 사용자 컴포넌트에 data-component-source-location을 주입합니다.
• componentAttributeName: null을 지정하면 사용자 컴포넌트에는 attribute를 주입하지 않습니다.
• 파일 경로의 query/hash 제거, Vite 가상 모듈 prefix 제거, OS 경로 구분자 정규화를 제공합니다.
• 이미 같은 이름의 attribute가 있으면 중복으로 주입하지 않습니다.

설치

bun add -D vite-plugin-jsx-source-attrs

npm을 사용한다면 다음처럼 설치합니다.

npm install -D vite-plugin-jsx-source-attrs

devDependency로 설치하는 이유

이 패키지는 Vite의 @vitejs/plugin-react Babel 설정에서 빌드 타임에만 실행됩니다. 런타임 브라우저 코드에서 import되는 패키지가 아니므로 일반 Vite 애플리케이션에서는 devDependencies에 설치하는 것이 권장값입니다.

프로덕션 빌드에서도 vite.config.ts를 평가해야 하므로 CI/CD가 devDependencies를 포함해 설치해야 합니다. npm ci --omit=dev처럼 devDependency를 제외한 상태에서 빌드를 실행하는 환경이라면 이 패키지를 찾을 수 없습니다. 이 경우 빌드 단계에서는 devDependency를 포함해 설치하고, 배포 런타임 이미지나 서버 산출물에서만 devDependency를 제외하세요.

LLM 적용 가이드 프롬프트

다른 Vite React 프로젝트에 이 패키지를 설치하고 vite.config.ts까지 자동 반영하려면 아래 프롬프트를 LLM/AI 에이전트에게 그대로 전달하세요. 더 자세한 지침은 README.llm.txt를 참고하세요.

Vite React 프로젝트에 `vite-plugin-jsx-source-attrs`를 설치하고 설정해줘.

요구사항:
1. 프로젝트 루트에서 패키지 매니저를 확인해줘.
   - `packageManager` 필드가 있으면 해당 도구를 우선 사용해줘.
   - `packageManager`가 없으면 lockfile 기준으로 판단해줘: `bun.lock` → Bun, `package-lock.json` → npm, `pnpm-lock.yaml` → pnpm, `yarn.lock` → Yarn.
   - 그래도 판단할 수 없으면 npm을 사용해줘.
2. `vite-plugin-jsx-source-attrs`를 devDependency로 설치해줘.
   - stable 검증이면 `vite-plugin-jsx-source-attrs` 또는 `vite-plugin-jsx-source-attrs@latest`를 설치해줘.
   - MR 검증본이 필요하면 `vite-plugin-jsx-source-attrs@dev`를 설치해줘.
   - main prerelease 검증본이 필요하면 `vite-plugin-jsx-source-attrs@pre`를 설치해줘.
3. `vite.config.ts` 또는 `vite.config.mts`를 찾아 `@vitejs/plugin-react`보다 앞에 `vitePluginJsxSourceAttrs()`를 추가해줘.
4. 기존 `react()` 설정, 기존 Babel plugin, alias, server, build 설정은 보존해줘.
5. 이미 `react({ babel: { plugins: [...] } })`를 지원하는 구버전 조합이면 `jsxSourceAttrs()`를 기존 Babel 플러그인 배열 끝에 추가해도 돼.
6. Vite 8 + `@vitejs/plugin-react` 6처럼 `babel` 옵션이 없는 조합에서는 `react({ babel: ... })` 형태로 바꾸지 말고 Vite 플러그인 방식을 사용해줘.
7. `defineConfig`가 객체 형태이고 `mode`가 필요하면 `defineConfig(({ mode }) => ({ ... }))` 형태로 바꿔줘. 단, 기존 설정 의미는 보존해줘.
8. 기본 설정은 아래 값을 사용해줘.

```ts
vitePluginJsxSourceAttrs({
  enabled: mode === 'development',
  attributeName: 'data-source-location',
  componentAttributeName: 'data-component-source-location',
})
```

9. import를 추가해줘.

```ts
import { vitePluginJsxSourceAttrs } from 'vite-plugin-jsx-source-attrs';
```

10. 기존 로컬 JSX source attrs 플러그인이 있으면 새 패키지로 대체해줘.
    - 제거 후보: `resources/scripts/jsx-source-attrs.js`, `resources/babel/jsx-source-attrs.js`, `src/resources/babel/jsx-source-attrs.js`, `@wix/babel-plugin-jsx-source-attrs` 직접 설정.
    - 단, 실제 import가 제거된 뒤에만 파일/의존성을 삭제해줘.
11. 빌드 단계에서는 devDependencies가 설치되어야 한다는 점을 CI 설정에서 확인해줘.
12. 변경 후 프로젝트의 기존 검증 스크립트를 실행해줘.
    - 가능한 경우: lint, typecheck, test, build 순서.
    - 없는 스크립트는 억지로 만들지 말고 건너뛰었다고 보고해줘.
13. 최종 보고에는 설치한 버전/tag, 수정한 파일, 실행한 검증 명령, 남은 주의사항을 요약해줘.

주의사항:
- unrelated 파일은 수정하지 마.
- 기존 변경사항을 되돌리지 마.
- 문자열/주석에 있는 예시는 실제 import나 실행 코드가 아니면 함부로 삭제하지 마.
- 프로덕션 빌드 산출물에는 `data-source-location`이 없어야 해.

사용법

Vite 8 + @vitejs/plugin-react 6처럼 React 플러그인의 babel.plugins 옵션을 사용할 수 없는 조합에서는 독립 Vite 플러그인으로 추가합니다.

import react from '@vitejs/plugin-react';
import { vitePluginJsxSourceAttrs } from 'vite-plugin-jsx-source-attrs';
import { defineConfig } from 'vite';

export default defineConfig(({ mode }) => ({
  plugins: [
    vitePluginJsxSourceAttrs({
      enabled: mode === 'development',
      attributeName: 'data-source-location',
      componentAttributeName: 'data-component-source-location',
    }),
    react(),
  ],
}));

@vitejs/plugin-react 4.x처럼 babel.plugins 옵션을 지원하는 조합에서는 Babel 플러그인 유틸리티를 직접 사용할 수도 있습니다.

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: 'data-component-source-location',
          }),
        ],
      },
    }),
  ],
}));

입력 JSX가 다음과 같다면,

const view = <div />;

개발 모드에서는 다음처럼 source location이 추가됩니다.

const view = <div data-source-location="src/App.tsx:1:14" />;

옵션

| 옵션 | 기본값 | 설명 | | --- | --- | --- | | enabled | Babel: process.env.NODE_ENV !== 'production', Vite: command === 'serve' | attribute 주입 여부입니다. boolean 또는 context 기반 함수로 지정할 수 있습니다. | | attributeName | data-source-location | intrinsic JSX 요소에 주입할 attribute 이름입니다. | | componentAttributeName | data-component-source-location | 사용자 컴포넌트에 별도로 주입할 attribute 이름입니다. null이면 사용자 컴포넌트에는 주입하지 않습니다. | | root | Babel: process.cwd(), Vite: config.root | 절대 경로를 상대 경로로 바꿀 기준 루트입니다. | | normalizePath | 내장 정규화 함수 | 파일 경로를 attribute 값에 맞게 정규화하는 함수입니다. | | include | /\.[jt]sx(?:\?.*)?$/ | vitePluginJsxSourceAttrs에서만 사용합니다. 변환할 Vite module id 패턴입니다. | | exclude | /\/node_modules\// | vitePluginJsxSourceAttrs에서만 사용합니다. 변환에서 제외할 Vite module id 패턴입니다. | | parserPlugins | [] | vitePluginJsxSourceAttrs에서만 사용합니다. 프로젝트 문법에 추가 Babel parser plugin이 필요할 때 지정합니다. |

enabled 함수 예시

jsxSourceAttrs({
  enabled: ({ filename }) => filename.endsWith('.tsx') && !filename.includes('/node_modules/'),
});

사용자 컴포넌트 attribute 비활성화 예시

jsxSourceAttrs({
  componentAttributeName: null,
});

경로 정규화

내장 normalizeSourcePath()는 다음 처리를 수행합니다.

• ?raw, ?import, #hash 같은 query/hash 제거
• Vite 가상 모듈 prefix인 \0, /@id/__x00__, /@fs/, virtual: 제거
• Windows 경로 구분자 \\를 /로 정규화
• root 하위 절대 경로를 상대 경로로 변환

저장소 구조

이 저장소는 단일 npm 패키지 repo입니다.

.
├── src/       # 배포되는 라이브러리 소스
├── test/      # Vitest 테스트
├── pipeline/  # GitLab CI publish/release 구성
└── docs/      # 배포와 마이그레이션 보조 문서

개발

아래 명령은 저장소 루트에서 실행합니다.

bun install
bun run lint
bun run typecheck
bun run test
bun run build

한 번에 검증하려면 다음 명령을 사용합니다.

bun run verify

배포

패키지 배포 산출물은 package.json의 files 필드와 .npmignore로 제한합니다. CI는 Bun 기반으로 검증하고, npm Registry와 GitLab Package Registry 배포 경로를 분리합니다.

자세한 내용은 docs/publishing.md를 참고하세요.

마이그레이션

기존 analytics 프로젝트의 로컬 jsx-source-attrs.js 복사본 또는 @wix/babel-plugin-jsx-source-attrs 직접 사용을 이 패키지로 바꾸는 방법은 docs/migration.md를 참고하세요.

라이선스

MIT