visual-remote 0.2.0 → 0.3.0

package/README.md

@@ -18,16 +18,20 @@ Node.js와 pnpm 버전은 각각 `.nvmrc`와 `package.json`에 고정되어 있
 
 ## 가장 빠른 사용
 
-Vite 앱의 `package.json`과 `vite.config`가 있는 폴더에서 한 번만 초기화합니다.
+Vite 또는 Next.js 앱의 `package.json`이 있는 폴더에서 한 번만 초기화합니다.
+Next.js 자동 통합은 `instrumentation-client`를 지원하는 Next.js 15.3 이상이
+필요합니다.
 
 ```bash
 npx --yes visual-remote@latest init
 ```
 
-`init`은 다음 작업을 수행합니다.
+`init`은 프로젝트 종류를 감지하고 다음 작업을 수행합니다.
 
 - 현재 프로젝트에 `visual-remote`를 개발 의존성으로 설치합니다.
-- `vite.config`의 플러그인 배열에 `visualRemote()`를 추가합니다.
+- Vite에서는 `vite.config`에 `visualRemote()` 플러그인을 추가합니다.
+- Next.js에서는 `next.config`에 `withVisualRemote()`를 적용하고
+  `instrumentation-client`에 개발 전용 클라이언트 로더를 추가합니다.
 - 현재 폴더에 `.visualdev/config.yaml`을 생성합니다.
 
 이후에는 앱을 평소처럼 실행합니다.
@@ -42,14 +46,16 @@ npm run dev
 
 ```text
 http://localhost:9011/api/*       → 기존 앱이 그대로 처리
-http://localhost:9011/@vite/*     → 기존 Vite/HMR이 그대로 처리
+http://localhost:9011/@vite/*     → 기존 Vite HMR이 그대로 처리
+http://localhost:9011/_next/*     → 기존 Next.js 자산/HMR이 그대로 처리
 http://localhost:9011/_visual/*   → 내부 Visual Remote Bridge로만 전달
 ```
 
-이미 실행 중이던 개발 서버가 있다면 `init` 후 한 번 재시작해야 변경된 Vite 설정이
+이미 실행 중이던 개발 서버가 있다면 `init` 후 한 번 재시작해야 변경된 설정이
 적용됩니다. Portr를 사용할 때도 내부 Bridge 포트가 아니라 기존 앱 포트만 노출합니다.
 
-현재 자동 통합은 Vite 프로젝트를 지원합니다.
+자동 통합은 Vite와 Next.js 프로젝트를 지원합니다. 다른 프레임워크나 설정 파일을
+자동으로 수정하고 싶지 않은 프로젝트에서는 아래의 `attach` 방식을 사용할 수 있습니다.
 
 ## 저장소에서 개발
 
@@ -98,7 +104,7 @@ corepack pnpm test
 ## 설정
 
 `init`은 명령을 실행한 현재 프로젝트 폴더에 설정을 생성합니다. 모노레포의 하위
-Vite 앱에서 실행하면 Git 루트가 아니라 해당 앱 폴더에 생성됩니다. 기존 설정은
+Vite 또는 Next.js 앱에서 실행하면 Git 루트가 아니라 해당 앱 폴더에 생성됩니다. 기존 설정은
 덮어쓰지 않습니다.
 
 ```yaml
@@ -156,8 +162,8 @@ paths:
     - dist/**
 ```
 
-Vite 플러그인이 개발 서버와 함께 내부 Bridge를 시작하고 종료합니다. `agent`,
-`verification`, `paths` 같은 상세 설정만 YAML에서 조정하면 됩니다.
+Vite 플러그인 또는 Next.js 설정 래퍼가 개발 서버와 함께 내부 Bridge를 시작합니다.
+`agent`, `verification`, `paths` 같은 상세 설정만 YAML에서 조정하면 됩니다.
 
 ## 기존 attach 방식
 
@@ -167,9 +173,9 @@ Vite 플러그인이 개발 서버와 함께 내부 Bridge를 시작하고 종
 npx --yes visual-remote@latest http://localhost:9011
 ```
 
-이 방식은 별도 Gateway 주소를 열어 앱 전체를 프록시하므로 Origin에 민감한 API나
-쿠키가 있는 앱에는 권장하지 않습니다. Vite 프로젝트에서는 `init` 통합을 사용하고
-원래 앱 주소로 접속합니다.
+이 방식은 별도 Gateway 주소를 열어 앱 전체를 프록시합니다. 자동 통합을 사용할 수
+있는 Vite와 Next.js 프로젝트에서는 `init`을 사용하고 원래 앱 주소로 접속합니다.
+설정 파일을 변경하지 않거나 다른 프레임워크에 붙일 때는 `attach`를 사용합니다.
 
 ## 브라우저에서 변경 요청
 
@@ -210,7 +216,7 @@ visual status
 visual doctor
 ```
 
-- `init`: 현재 Vite 앱에 개발 전용 통합을 설치합니다.
+- `init`: 현재 Vite 또는 Next.js 앱에 개발 전용 통합을 설치합니다.
 - `attach`: 기본 명령의 명시적 이름이며 기존 사용법과 호환됩니다.
 - `dev`: `init` 설정을 사용해 앱과 브리지를 함께 실행하는 선택 명령입니다.
 - `status`: 현재 Git 작업 트리의 브리지 실행 상태를 확인합니다.
@@ -239,6 +245,8 @@ packages/overlay/dist/client.js
 packages/overlay/dist/viewer.js
 apps/cli/dist/index.js
 apps/cli/dist/vite.js
+apps/cli/dist/next.js
+apps/cli/dist/next-client.js
 ```
 
 ## 저장소 구조
@@ -278,6 +286,7 @@ node --version
 
 ### 설정 파일 경고가 표시되는 경우
 
-Vite 앱의 `package.json`과 `vite.config`가 있는 폴더에서 `visual init`을 실행한 뒤
-`doctor`를 다시 실행합니다. 모노레포에서는 Git 루트가 아니라 실제 앱 폴더에서
-실행합니다.
+Vite 또는 Next.js 앱의 `package.json`이 있는 폴더에서 `visual init`을 실행한 뒤
+`doctor`를 다시 실행합니다. Vite는 `vite.config`, Next.js는 `next.config`와
+`instrumentation-client`가 구성되어야 합니다. 모노레포에서는 Git 루트가 아니라
+실제 앱 폴더에서 실행합니다.

package/apps/cli/dist/index.js

@@ -5234,6 +5234,20 @@ var VITE_CONFIG_FILES = [
   "vite.config.mjs"
 ];
 var VITE_IMPORT = 'import { visualRemote } from "visual-remote/vite";';
+var NEXT_CONFIG_FILES = [
+  "next.config.ts",
+  "next.config.mjs",
+  "next.config.js"
+];
+var NEXT_ESM_IMPORT = 'import { withVisualRemote } from "visual-remote/next";';
+var NEXT_CJS_IMPORT = 'const { withVisualRemote } = require("visual-remote/next");';
+var NEXT_CLIENT_MODULE = "visual-remote/next/client";
+var NEXT_CLIENT_BOOTSTRAP = [
+  'if (process.env.NODE_ENV === "development") {',
+  `  void import("${NEXT_CLIENT_MODULE}");`,
+  "}",
+  ""
+].join("\n");
 function isMissingFile(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
@@ -5284,6 +5298,13 @@ function isViteProject(manifest, devScript) {
   };
   return "vite" in packages || /(^|[\s;&|])vite(?:\s|$)/.test(devScript);
 }
+function isNextProject(manifest, devScript) {
+  const packages = {
+    ...packageRecord(manifest.dependencies),
+    ...packageRecord(manifest.devDependencies)
+  };
+  return "next" in packages || /(^|[\s;&|])next(?:\s|$)/.test(devScript);
+}
 function hasVisualRemote(manifest) {
   return "visual-remote" in packageRecord(manifest.dependencies) || "visual-remote" in packageRecord(manifest.devDependencies);
 }
@@ -5330,6 +5351,13 @@ async function findViteConfig(projectRoot) {
     "visual init found Vite but could not find vite.config.ts, .mts, .js, or .mjs"
   );
 }
+async function findNextConfig(projectRoot) {
+  for (const filename of NEXT_CONFIG_FILES) {
+    const candidate = join5(projectRoot, filename);
+    if (await fileExists2(candidate)) return candidate;
+  }
+  return join5(projectRoot, "next.config.mjs");
+}
 function insertViteImport(source) {
   const lines = source.split("\n");
   let index = 0;
@@ -5367,6 +5395,130 @@ async function configureVite(configPath) {
   await writeFile3(configPath, transformed, "utf8");
   return true;
 }
+function expressionEnd(source, expressionStart) {
+  let roundDepth = 0;
+  let squareDepth = 0;
+  let curlyDepth = 0;
+  let quote;
+  let lineComment = false;
+  let blockComment = false;
+  for (let index = expressionStart; index < source.length; index += 1) {
+    const character = source[index];
+    const nextCharacter = source[index + 1];
+    if (lineComment) {
+      if (character === "\n") lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (character === "*" && nextCharacter === "/") {
+        blockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (quote !== void 0) {
+      if (character === "\\") {
+        index += 1;
+      } else if (character === quote) {
+        quote = void 0;
+      }
+      continue;
+    }
+    if (character === "/" && nextCharacter === "/") {
+      lineComment = true;
+      index += 1;
+      continue;
+    }
+    if (character === "/" && nextCharacter === "*") {
+      blockComment = true;
+      index += 1;
+      continue;
+    }
+    if (character === "'" || character === '"' || character === "`") {
+      quote = character;
+      continue;
+    }
+    if (character === "(") roundDepth += 1;
+    if (character === ")") roundDepth -= 1;
+    if (character === "[") squareDepth += 1;
+    if (character === "]") squareDepth -= 1;
+    if (character === "{") curlyDepth += 1;
+    if (character === "}") curlyDepth -= 1;
+    if (character === ";" && roundDepth === 0 && squareDepth === 0 && curlyDepth === 0) {
+      return index;
+    }
+  }
+  return source.length;
+}
+function wrapConfigExpression(source, assignmentPattern) {
+  const assignment = assignmentPattern.exec(source);
+  if (assignment?.index === void 0) {
+    throw new Error("visual init could not find the default Next.js config export");
+  }
+  let start = assignment.index + assignment[0].length;
+  while (/\s/.test(source[start] ?? "")) start += 1;
+  const end = expressionEnd(source, start);
+  const rawExpression = source.slice(start, end);
+  const trailingWhitespace = rawExpression.match(/\s*$/)?.[0] ?? "";
+  const expression = rawExpression.slice(0, rawExpression.length - trailingWhitespace.length);
+  if (expression.length === 0) {
+    throw new Error("visual init found an empty Next.js config export");
+  }
+  return `${source.slice(0, start)}withVisualRemote(${expression})${trailingWhitespace}${source.slice(end)}`;
+}
+function transformNextConfig(source) {
+  if (source.includes("visual-remote/next") && /\bwithVisualRemote\s*\(/.test(source)) {
+    return source;
+  }
+  if (/\bmodule\.exports\s*=/.test(source)) {
+    const wrapped2 = wrapConfigExpression(source, /\bmodule\.exports\s*=/);
+    return wrapped2.includes(NEXT_CJS_IMPORT) ? wrapped2 : `${NEXT_CJS_IMPORT}
+${wrapped2}`;
+  }
+  const wrapped = wrapConfigExpression(source, /\bexport\s+default\b/);
+  return wrapped.includes(NEXT_ESM_IMPORT) ? wrapped : `${NEXT_ESM_IMPORT}
+${wrapped}`;
+}
+async function configureNext(configPath) {
+  let source;
+  try {
+    source = await readFile5(configPath, "utf8");
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+    source = "export default {};\n";
+  }
+  const transformed = transformNextConfig(source);
+  if (transformed === source) return false;
+  await writeFile3(configPath, transformed, "utf8");
+  return true;
+}
+async function findNextClientPath(projectRoot) {
+  const candidates = [
+    join5(projectRoot, "instrumentation-client.ts"),
+    join5(projectRoot, "instrumentation-client.js"),
+    join5(projectRoot, "src", "instrumentation-client.ts"),
+    join5(projectRoot, "src", "instrumentation-client.js")
+  ];
+  for (const candidate of candidates) {
+    if (await fileExists2(candidate)) return candidate;
+  }
+  const sourceRoot = await fileExists2(join5(projectRoot, "src")) ? join5(projectRoot, "src") : projectRoot;
+  const extension = await fileExists2(join5(projectRoot, "tsconfig.json")) ? "ts" : "js";
+  return join5(sourceRoot, `instrumentation-client.${extension}`);
+}
+async function configureNextClient(clientPath) {
+  let source = "";
+  try {
+    source = await readFile5(clientPath, "utf8");
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+  }
+  if (source.includes(NEXT_CLIENT_MODULE)) return false;
+  const separator = source.length === 0 || source.endsWith("\n") ? "" : "\n";
+  await mkdir3(dirname4(clientPath), { recursive: true });
+  await writeFile3(clientPath, `${source}${separator}${NEXT_CLIENT_BOOTSTRAP}`, "utf8");
+  return true;
+}
 function installCommand(request) {
   if (request.packageManager === "pnpm") {
     return {
@@ -5416,11 +5568,12 @@ async function initializeVisualDev(dependencies = {}) {
   const repoRoot = await discoverGitWorktreeRoot(projectRoot);
   const manifest = await readManifest(projectRoot);
   const devScript = readDevScript(manifest);
-  if (!isViteProject(manifest, devScript)) {
-    throw new Error("visual init currently supports Vite projects");
+  const framework = isViteProject(manifest, devScript) ? "vite" : isNextProject(manifest, devScript) ? "next" : void 0;
+  if (framework === void 0) {
+    throw new Error("visual init currently supports Vite and Next.js projects");
   }
   const packageManager = await detectPackageManager(projectRoot, repoRoot, manifest);
-  const integrationPath = await findViteConfig(projectRoot);
+  const integrationPath = framework === "vite" ? await findViteConfig(projectRoot) : await findNextConfig(projectRoot);
   const packageInstalled = !hasVisualRemote(manifest);
   if (packageInstalled) {
     await (dependencies.installPackage ?? installPackage)({
@@ -5429,7 +5582,9 @@ async function initializeVisualDev(dependencies = {}) {
       packageSpec: "visual-remote@latest"
     });
   }
-  const integrationChanged = await configureVite(integrationPath);
+  const integrationChanged = framework === "vite" ? await configureVite(integrationPath) : await configureNext(integrationPath);
+  const clientPath = framework === "next" ? await findNextClientPath(projectRoot) : void 0;
+  const clientChanged = clientPath === void 0 ? void 0 : await configureNextClient(clientPath);
   const configPath = join5(projectRoot, CONFIG_PATH);
   const created = !await fileExists2(configPath);
   if (created) {
@@ -5461,24 +5616,35 @@ async function initializeVisualDev(dependencies = {}) {
     }
   }
   return {
+    framework,
     created,
     configPath,
     devScript,
     packageManager,
     integrationPath,
     integrationChanged,
+    ...clientPath === void 0 || clientChanged === void 0 ? {} : { clientPath, clientChanged },
     packageInstalled
   };
 }
 function formatInitResult(result) {
   const configLabel = result.created ? "Created" : "Existing";
   const integrationLabel = result.integrationChanged ? "Configured" : "Existing";
-  return [
+  const rows = [
+    `Framework: ${result.framework === "next" ? "Next.js" : "Vite"}`,
     `${configLabel}:   ${relative7(process.cwd(), result.configPath) || CONFIG_PATH}`,
-    `${integrationLabel}: ${relative7(process.cwd(), result.integrationPath)}`,
+    `${integrationLabel}: ${relative7(process.cwd(), result.integrationPath)}`
+  ];
+  if (result.clientPath !== void 0) {
+    rows.push(
+      `${result.clientChanged ? "Configured" : "Existing"}: ${relative7(process.cwd(), result.clientPath)}`
+    );
+  }
+  rows.push(
     result.packageInstalled ? "Installed: visual-remote@latest" : "Installed: visual-remote",
     "Next:      Start the app normally and open its original URL."
-  ].join("\n");
+  );
+  return rows.join("\n");
 }
 
 // src/status.ts
@@ -5531,8 +5697,8 @@ function setExitCode(dependencies, code) {
   }
 }
 function createCli(dependencies = {}) {
-  const program = new Command().name("visual").description("Visual Remote Dev Bridge").version("0.2.0");
-  program.command("init").description("Create .visualdev/config.yaml for the current project").action(async () => {
+  const program = new Command().name("visual").description("Visual Remote Dev Bridge").version("0.3.0");
+  program.command("init").description("Configure Visual Remote for the current Vite or Next.js project").action(async () => {
     const result = await initializeVisualDev(dependencies);
     output(dependencies, formatInitResult(result));
   });
@@ -5611,5 +5777,6 @@ export {
   runDoctor,
   startAttachBridge,
   startManagedBridge,
+  transformNextConfig,
   transformViteConfig
 };

package/apps/cli/dist/next-client.js

@@ -0,0 +1,11 @@
+// src/next-client.ts
+var clientPath = "/_visual/client.js";
+if (document.querySelector(`script[src="${clientPath}"]`) === null && document.querySelector("script[data-visual-remote-client]") === null) {
+  const script = document.createElement("script");
+  script.type = "module";
+  script.src = clientPath;
+  script.dataset.visualRemoteClient = "";
+  const nonceSource = document.querySelector("script[nonce]");
+  if (nonceSource?.nonce) script.nonce = nonceSource.nonce;
+  document.head.append(script);
+}