react-code-locator 0.1.17 → 0.2.0

package/README.md

@@ -2,9 +2,10 @@
 
 개발 중인 React 앱에서 요소를 `Shift + Click`하면 해당 UI와 연결된 소스 위치를 찾는 패키지입니다.
 
-- React element 생성 시 source metadata를 붙이고, 브라우저 런타임에서 Fiber를 따라 위치를 계산합니다.
-- JSX 디버그 정보가 있으면 우선 사용하고, 없으면 컴포넌트 정의 위치로 fallback 합니다.
-- Babel, Vite, esbuild, SWC 파이프라인용 어댑터와 브라우저 런타임을 분리해서 사용할 수 있습니다.
+- React element 생성 시 source metadata를 주입하고, 브라우저 런타임에서 Fiber를 따라 위치를 계산합니다.
+- **완전 번들링**: acorn 기반 순수 JS 파서를 내장 — 별도 파서 설치 불필요
+- **Universal**: Vite, Webpack, Rollup, esbuild, Rspack 모두 지원
+- **개발 전용**: 프로덕션 빌드에 영향 없음
 
 ## 설치
 
@@ -12,338 +13,160 @@
 npm i -D react-code-locator
 ```
 
-로컬 패키지로 연결할 때는:
-
-```bash
-npm i -D /absolute/path/to/react-code-locator
-```
+> Vite / Rollup / esbuild / Rspack 플러그인을 사용하려면 `unplugin`도 필요합니다.
+>
+> ```bash
+> npm i -D unplugin
+> ```
+>
+> Webpack은 unplugin 없이 동작합니다.
 
 ## 빠른 시작
 
-Vite 환경에서는 `createViteSourceAdapter()`가 source transform과 클라이언트 자동 주입을 함께 제공합니다.
-
-```ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import { createViteSourceAdapter } from "react-code-locator/vite";
-
-export default defineConfig(({ command }) => ({
-  plugins: [
-    react(),
-    ...createViteSourceAdapter({
-      command,
-      locator: { triggerKey: "shift" },
-    }).config.plugins,
-  ],
-}));
-```
-
-개발 서버에서 `Shift + Click`하면 브라우저 콘솔에 이런 식으로 출력됩니다.
-
-```text
-[react-code-locator] src/components/Button.tsx:14:1 [jsx]
-```
-
-## 제공 엔트리
+### Vite
 
-### `react-code-locator/vite`
-
-Vite + React 프로젝트용 기본 진입점입니다.
-
-- source transform 플러그인과 브라우저 클라이언트 주입 플러그인을 함께 제공합니다.
-- HTML에는 bare import를 직접 넣지 않고 Vite 가상 모듈을 통해 클라이언트를 로드합니다.
-- 기본값으로 브라우저 클라이언트도 자동 주입합니다.
+`vitePlugin`은 소스 transform + 클라이언트 런타임 자동 주입을 모두 처리합니다.
 
 ```ts
+// vite.config.ts
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
-import { createViteSourceAdapter } from "react-code-locator/vite";
+import { vitePlugin } from "react-code-locator";
 
-export default defineConfig(({ command }) => ({
+export default defineConfig({
   plugins: [
     react(),
-    ...createViteSourceAdapter({
-      command,
-      locator: { triggerKey: "shift" },
-      injectClient: true,
-    }).config.plugins,
+    vitePlugin(),
   ],
-}));
-```
-
-옵션:
-
-- `command`: `"serve" | "build"` , 보통 Vite의 `command` 그대로 전달
-- `locator.triggerKey`: `"alt" | "meta" | "ctrl" | "shift" | "none"`
-- `locator.onLocate(result)`: 위치를 찾았을 때 커스텀 처리
-- `locator.onError(error)`: 위치를 못 찾았을 때 커스텀 처리
-- `injectClient`: `false`로 두면 브라우저 런타임 자동 주입 비활성화
-- `babel`: source transform 옵션
-
-### `react-code-locator/client`
-
-브라우저 런타임만 수동으로 붙이고 싶을 때 사용합니다.
-
-```ts
-import { enableReactComponentJump } from "react-code-locator/client";
-
-const dispose = enableReactComponentJump({
-  triggerKey: "shift",
-  onLocate(result) {
-    console.log("located:", result.source, result.mode);
-  },
 });
-
-// 필요 시 해제
-dispose();
-```
-
-자동 주입을 끄고 직접 붙이는 예시:
-
-```ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import { createViteSourceAdapter } from "react-code-locator/vite";
-
-export default defineConfig(({ command }) => ({
-  plugins: [
-    react(),
-    ...createViteSourceAdapter({
-      command,
-      injectClient: false,
-    }).config.plugins,
-  ],
-}));
-```
-
-그 다음 앱 엔트리에서:
-
-```ts
-import { enableReactComponentJump } from "react-code-locator/client";
-
-if (import.meta.env.DEV) {
-  enableReactComponentJump();
-}
 ```
 
-### `react-code-locator/babel`
-
-Babel 플러그인만 따로 사용할 때 사용합니다.
-
-이 플러그인은 기본적으로 두 가지를 주입합니다.
-
-- 커스텀 React 컴포넌트 JSX 호출부에 `$componentSourceLoc`
-- React 컴포넌트 함수/클래스에 `__componentSourceLoc`
-- intrinsic DOM JSX는 prop이 아니라 숨겨진 registry metadata로 추적합니다.
+### Next.js (Webpack)
 
 ```js
-const { babelInjectComponentSource } = require("react-code-locator/babel");
+// next.config.js
+const { webpackPlugin } = require("react-code-locator/webpack");
 
 module.exports = {
-  plugins: [babelInjectComponentSource],
+  webpack(config, { dev }) {
+    if (dev) {
+      config.plugins.push(webpackPlugin());
+    }
+    return config;
+  },
 };
 ```
 
-ESM 설정 예시:
+### Create React App
 
-```ts
-import { babelInjectComponentSource } from "react-code-locator/babel";
+```js
+// config-overrides.js
+const { webpackPlugin } = require("react-code-locator/webpack");
 
-export default {
-  plugins: [babelInjectComponentSource],
+module.exports = {
+  webpack(config, env) {
+    if (env === "development") {
+      config.plugins.push(webpackPlugin());
+    }
+    return config;
+  },
 };
 ```
 
-JSX 호출부 주입을 끄고 싶으면:
+### Rollup
 
-```ts
-import { babelInjectComponentSource } from "react-code-locator/babel";
+```js
+// rollup.config.js
+import { rollupPlugin } from "react-code-locator";
 
 export default {
-  plugins: [[babelInjectComponentSource, { injectJsxSource: false }]],
+  plugins: [rollupPlugin()],
 };
 ```
 
-### `react-code-locator/webpack`
-
-Webpack 설정에 Babel 플러그인과 런타임 엔트리를 함께 주입합니다.
+### esbuild
 
 ```js
-const { withReactComponentJump } = require("react-code-locator/webpack");
-const config = createExistingWebpackConfig();
+import { esbuildPlugin } from "react-code-locator";
 
-module.exports = withReactComponentJump(config, {
-  env: process.env.NODE_ENV,
+await esbuild.build({
+  plugins: [esbuildPlugin()],
 });
 ```
 
-동작 방식:
-
-- `env !== "development"`이면 원본 config를 그대로 반환
-- `babel-loader`를 찾아 `babelInjectComponentSource`를 추가
-- 엔트리 앞에 런타임 스크립트를 prepend
-
-전제:
-
-- React 앱이 Babel을 통해 트랜스파일되어야 합니다.
-- `module.rules` 안에 `babel-loader`가 있어야 자동 주입이 동작합니다.
-
-### `react-code-locator/esbuild`
-
-esbuild 파이프라인에 source transform 플러그인을 붙일 때 사용합니다.
-
-```ts
-import { createEsbuildSourceAdapter } from "react-code-locator/esbuild";
-
-const locator = createEsbuildSourceAdapter();
-const plugins = [...locator.config.plugins];
-```
-
-### `react-code-locator/swc`
-
-SWC 기반 파이프라인에서 공통 source transform을 호출할 때 사용합니다.
-
-```ts
-import { createSwcSourceAdapter } from "react-code-locator/swc";
-
-const locator = createSwcSourceAdapter();
-const transform = locator.config.transform;
-```
-
-### `react-code-locator/unplugin` ⭐ New
-
-**unplugin** 기반 통합 어댑터입니다. Vite, Webpack, Rollup, esbuild, Rspack 모두 지원하며, **Babel 없이** acorn 기반으로 동작합니다.
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import { vitePlugin as reactCodeLocator } from "react-code-locator/unplugin";
-
-export default defineConfig({
-  plugins: [
-    react(),
-    reactCodeLocator(),
-  ],
-});
-```
+### Rspack
 
 ```js
-// webpack.config.js
-const { webpackPlugin } = require("react-code-locator/unplugin");
+// rspack.config.js
+const { rspackPlugin } = require("react-code-locator");
 
 module.exports = {
-  plugins: [reactCodeLocator()],
+  plugins: [rspackPlugin()],
 };
 ```
 
-```js
-// rollup.config.js
-import { rollupPlugin } from "react-code-locator/unplugin";
-
-export default {
-  plugins: [reactCodeLocator()],
-};
-```
+## 옵션
 
-옵션:
+모든 플러그인이 동일한 옵션을 공유합니다.
 
 ```ts
-reactCodeLocator({
-  projectRoot: process.cwd(),    // 프로젝트 루트 경로
+vitePlugin({
+  // 소스 transform 옵션
+  projectRoot: process.cwd(),    // 프로젝트 루트 (상대 경로 기준)
   injectComponentSource: true,   // 컴포넌트 정의에 소스 주입
   injectJsxSource: true,         // JSX 호출부에 소스 주입
   include: /\.[jt]sx$/,          // 포함할 파일 패턴
   exclude: /node_modules/,       // 제외할 파일 패턴
-});
-```
-
-**주의:** unplugin 어댑터를 사용하려면 `acorn`, `astring`, `estree-walker`, `unplugin`을 설치해야 합니다.
 
-```bash
-npm install -D acorn astring estree-walker unplugin
+  // Vite 전용 옵션
+  injectClient: true,            // 클라이언트 런타임 자동 주입 (기본값: true)
+  locator: {                     // 런타임 옵션
+    triggerKey: "shift",         // 트리거 키 (기본값: "shift")
+  },
+});
 ```
 
-### `react-code-locator`
+## 사용
 
-런타임 유틸만 직접 사용할 때의 기본 엔트리입니다.
+개발 서버에서 `Shift + Click`하면 브라우저 콘솔에 소스 위치가 출력됩니다.
 
-```ts
-import { enableReactComponentJump, locateComponentSource } from "react-code-locator";
 ```
-
-루트 엔트리는 브라우저 런타임 전용입니다.
-빌드 도구 어댑터는 반드시 각 subpath에서 가져와야 합니다.
-
-- Babel: `react-code-locator/babel`
-- Vite: `react-code-locator/vite`
-- esbuild: `react-code-locator/esbuild`
-- SWC: `react-code-locator/swc`
-- Webpack: `react-code-locator/webpack`
-
-제공 API:
-
-- `enableReactComponentJump(options)`
-- `locateComponentSource(target)`
-
-`locateComponentSource` 반환값:
-
-```ts
-type LocatorResult = {
-  source: string;
-  mode: "direct" | "screen" | "implementation";
-};
+[react-code-locator] src/components/Button.tsx:14:1
 ```
 
-## 사용 흐름
+결과를 클릭하면 클립보드에 복사됩니다.
 
-정상 동작하려면 보통 아래 두 단계가 같이 필요합니다.
+### 단축키
 
-1. 빌드 단계에서 source transform으로 소스 메타데이터 주입
-2. 브라우저에서 클릭 이벤트를 가로채 React Fiber를 따라가며 위치 계산
+| 키 | 동작 |
+|----|------|
+| `Shift + Click` | 소스 위치 찾기 |
+| `Alt + 1` | direct 모드 (JSX 호출부 위치) |
+| `Alt + 2` | screen 모드 (화면에 보이는 컴포넌트) |
+| `Alt + 3` | implementation 모드 (구현체 위치) |
 
-Vite/webpack 어댑터를 쓰면 이 둘을 한 번에 붙일 수 있습니다.
+## 수동 설정 (고급)
 
-## 개발/배포 스크립트
+Vite가 아닌 환경에서는 클라이언트 런타임을 직접 초기화해야 합니다.
 
-```bash
-npm run build
-```
-
-- 라이브러리만 `dist/`로 빌드합니다.
+```ts
+import { enableReactComponentJump } from "react-code-locator/client";
 
-```bash
-npm run deploy --otp=123456
+enableReactComponentJump({
+  triggerKey: "shift",
+  onLocate(result) {
+    console.log("Source:", result.source);
+  },
+});
 ```
 
-- `build`
-- `npm pack --dry-run`
-- `npm publish --access public`
-
-순서로 실행합니다.
-
-## peerDependencies
-
-- `@babel/core >= 7`
-- `@vitejs/plugin-react >= 4`
-
-둘 다 optional peer dependency입니다.
-
-- Babel 플러그인을 직접 쓰거나 Vite 어댑터를 쓸 때 필요할 수 있습니다.
-- Webpack 런타임만 소비하는 쪽에서는 사용 방식에 따라 일부만 필요할 수 있습니다.
-
-## 주의점
+## 알려진 제한사항
 
-- 개발 모드 전용입니다.
-- React 내부 필드인 Fiber와 `_debugSource`에 의존합니다.
-- production build에서는 JSX 디버그 정보가 없어질 수 있습니다.
-- 클릭 이벤트를 capture 단계에서 가로채므로, modifier key가 눌리면 기본 클릭 동작이 막힐 수 있습니다.
-- `triggerKey: "none"`이면 모든 클릭에서 동작하므로 일반적으로 권장하지 않습니다.
+- **React Native 미지원**: DOM API에 의존합니다.
+- **Turbopack 미지원**: Next.js 13+의 Turbopack은 현재 지원되지 않습니다.
+- **TSX generic arrow function**: `.tsx` 파일에서 `<T,>` 형태의 제네릭 화살표 함수가 있는 파일은 transform이 스킵됩니다. (`function` 선언형이나 `.ts` 파일에서는 정상 동작합니다.)
+- **개발 전용**: `NODE_ENV=development` 환경에서만 사용하세요.
 
-## 주요 파일
+## License
 
-- `src/runtime.ts`: 클릭 이벤트 처리와 React Fiber 기반 소스 탐색
-- `src/babelInjectComponentSource.ts`: Babel 메타데이터 주입
-- `src/vite.ts`: Vite 어댑터 export
-- `src/webpack.cts`: Webpack 어댑터 export
-- `src/client.ts`: 브라우저 런타임 export
+MIT