@revyse/next 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @revyse/next
 
-Next.js integration for Revyse: in development builds only, tags elements with their source
-location and injects the Revyse overlay served by the local agent (`npx revyse dev`). A
-production build is untouched; a test proves it.
+Next.js integration for Revyse: in `next dev` only, starts the local agent, tags elements with
+their source location and injects the Revyse overlay, so there is no separate `revyse dev` to
+run. A production build is untouched; a test proves it.
 
 ```ts
 // next.config.ts

package/dist/index.cjs

@@ -33,6 +33,8 @@ __export(src_exports, {
   DEFAULT_AGENT_PORT: () => DEFAULT_AGENT_PORT,
   DEFAULT_APP_URL: () => DEFAULT_APP_URL,
   LOCATIONS_DIR: () => LOCATIONS_DIR,
+  configuredAgentPort: () => configuredAgentPort,
+  ensureLocalAgent: () => ensureLocalAgent,
   liveLoaderScript: () => liveLoaderScript,
   pagesRouterOf: () => pagesRouterOf,
   withRevyse: () => withRevyse
@@ -53,6 +55,44 @@ var DEFAULT_APP_URL = "https://revyse.dev";
 var PHASE_DEVELOPMENT_SERVER = "phase-development-server";
 var PHASE_PRODUCTION_BUILD = "phase-production-build";
 var require_ = (0, import_node_module.createRequire)(importMetaUrl);
+function configuredAgentPort(root) {
+  try {
+    const config = JSON.parse((0, import_node_fs.readFileSync)(import_node_path.default.join(root, "revyse.config.json"), "utf8"));
+    return typeof config.agentPort === "number" ? config.agentPort : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var say = (msg) => console.log(`[revyse] ${msg}`);
+var warn = (msg) => console.warn(`[revyse] ${msg}`);
+var agentStart;
+function ensureLocalAgent(root, load = () => import("revyse/agent")) {
+  if (process.env.REVYSE_AGENT === "off") return Promise.resolve();
+  agentStart ??= startAgent(root, load).catch(
+    (err) => warn(
+      `Couldn't start Revyse (${err.message}). Check that \`revyse\` is installed as a dev dependency, or run \`npx revyse dev\`.`
+    )
+  );
+  return agentStart;
+}
+async function startAgent(root, load) {
+  if (!(0, import_node_fs.existsSync)(import_node_path.default.join(root, "revyse.config.json"))) {
+    warn("This app isn't set up for Revyse yet: run `npx revyse init`.");
+    return;
+  }
+  const { startLocalAgent } = await load();
+  const started = await startLocalAgent({ root, log: say });
+  if (started.status === "running") return;
+  if (started.status === "taken") {
+    warn(
+      started.root ? `Port ${started.port} is used by Revyse for ${started.root}, so the overlay here would talk to that project. Set "agentPort" in revyse.config.json to another port, such as ${started.port + 1}.` : `Port ${started.port} is in use by another program. Set "agentPort" in revyse.config.json to a free port.`
+    );
+    return;
+  }
+  say(
+    started.agent.connected ? "Ready: open your app and click the Revyse button." : "Ready, but this project isn't connected to Revyse yet: run `npx revyse init` to connect it."
+  );
+}
 function pagesRouterOf(root) {
   for (const dir of ["pages", "src/pages"]) {
     if (!(0, import_node_fs.existsSync)(import_node_path.default.join(root, dir))) continue;
@@ -87,7 +127,9 @@ function withRevyse(config = {}, options = {}) {
       return resolved;
     }
     const projectRoot = options.projectRoot ?? process.cwd();
-    const overlayScriptUrl = `http://127.0.0.1:${options.agentPort ?? DEFAULT_AGENT_PORT}/overlay.js`;
+    const agentPort = options.agentPort ?? configuredAgentPort(projectRoot) ?? DEFAULT_AGENT_PORT;
+    const overlayScriptUrl = `http://127.0.0.1:${agentPort}/overlay.js`;
+    void ensureLocalAgent(projectRoot);
     const loader = {
       loader: require_.resolve("@revyse/next/loader"),
       options: { projectRoot, overlayScriptUrl }
@@ -183,6 +225,8 @@ function withLiveLoader(resolved, projectRoot, live) {
   DEFAULT_AGENT_PORT,
   DEFAULT_APP_URL,
   LOCATIONS_DIR,
+  configuredAgentPort,
+  ensureLocalAgent,
   liveLoaderScript,
   pagesRouterOf,
   withRevyse

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { NextConfig } from 'next';
 
 interface RevyseNextOptions {
-    /** Port of the local Revyse agent started by `revyse dev`. */
+    /** Port of the local Revyse agent; defaults to `agentPort` in `revyse.config.json`, then 4545. */
     agentPort?: number;
     /** Project root; defaults to the directory Next runs in. */
     projectRoot?: string;
@@ -33,6 +33,35 @@ declare const DEFAULT_APP_URL = "https://revyse.dev";
 type ConfigInput = NextConfig | ((phase: string, ctx: {
     defaultConfig: NextConfig;
 }) => NextConfig | Promise<NextConfig>);
+/** `agentPort` from the project's `revyse.config.json`, if it has one. */
+declare function configuredAgentPort(root: string): number | undefined;
+/** What `withRevyse()` uses from `revyse/agent` (the CLI package's local agent). */
+interface AgentModule {
+    startLocalAgent(opts: {
+        root: string;
+        log: (msg: string) => void;
+    }): Promise<{
+        status: "started";
+        agent: {
+            url: string;
+            connected: boolean;
+        };
+    } | {
+        status: "running";
+        port: number;
+    } | {
+        status: "taken";
+        port: number;
+        root: string | null;
+    }>;
+}
+/**
+ * Starts the local agent inside `next dev` (L14, ADR 0041), so the overlay works without
+ * `revyse dev`. Next 15 runs the config in its CLI process and its server process: whichever
+ * comes second finds this project's agent on the port and leaves it be. `REVYSE_AGENT=off`
+ * turns it off; `load` is for tests.
+ */
+declare function ensureLocalAgent(root: string, load?: () => Promise<AgentModule>): Promise<void>;
 /** The Pages Router directory and whether it has a custom `_document`, if the app has one. */
 declare function pagesRouterOf(root: string): {
     dir: string;
@@ -44,8 +73,9 @@ declare function liveLoaderScript(live: NonNullable<RevyseNextOptions["live"]>):
     projectKey: string;
 };
 /**
- * Wraps a Next.js config. In `next dev` it adds a JSX loader (webpack and Turbopack) that tags
- * host elements with their source location and loads the Revyse overlay. In every other phase
+ * Wraps a Next.js config. In `next dev` it starts the local agent (L14) and adds a JSX loader
+ * (webpack and Turbopack) that tags host elements with their source location and loads the
+ * Revyse overlay. In every other phase
  * — including `next build` — the config is returned untouched, so nothing ships to production,
  * with one opt-in exception: `live` adds the live overlay's loader tag to production builds.
  */
@@ -53,5 +83,5 @@ declare function withRevyse(config?: ConfigInput, options?: RevyseNextOptions):
     defaultConfig: NextConfig;
 }) => Promise<NextConfig>;
 
-export { DEFAULT_AGENT_PORT, DEFAULT_APP_URL, LOCATIONS_DIR, liveLoaderScript, pagesRouterOf, withRevyse };
-export type { RevyseNextOptions };
+export { DEFAULT_AGENT_PORT, DEFAULT_APP_URL, LOCATIONS_DIR, configuredAgentPort, ensureLocalAgent, liveLoaderScript, pagesRouterOf, withRevyse };
+export type { AgentModule, RevyseNextOptions };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NextConfig } from 'next';
 
 interface RevyseNextOptions {
-    /** Port of the local Revyse agent started by `revyse dev`. */
+    /** Port of the local Revyse agent; defaults to `agentPort` in `revyse.config.json`, then 4545. */
     agentPort?: number;
     /** Project root; defaults to the directory Next runs in. */
     projectRoot?: string;
@@ -33,6 +33,35 @@ declare const DEFAULT_APP_URL = "https://revyse.dev";
 type ConfigInput = NextConfig | ((phase: string, ctx: {
     defaultConfig: NextConfig;
 }) => NextConfig | Promise<NextConfig>);
+/** `agentPort` from the project's `revyse.config.json`, if it has one. */
+declare function configuredAgentPort(root: string): number | undefined;
+/** What `withRevyse()` uses from `revyse/agent` (the CLI package's local agent). */
+interface AgentModule {
+    startLocalAgent(opts: {
+        root: string;
+        log: (msg: string) => void;
+    }): Promise<{
+        status: "started";
+        agent: {
+            url: string;
+            connected: boolean;
+        };
+    } | {
+        status: "running";
+        port: number;
+    } | {
+        status: "taken";
+        port: number;
+        root: string | null;
+    }>;
+}
+/**
+ * Starts the local agent inside `next dev` (L14, ADR 0041), so the overlay works without
+ * `revyse dev`. Next 15 runs the config in its CLI process and its server process: whichever
+ * comes second finds this project's agent on the port and leaves it be. `REVYSE_AGENT=off`
+ * turns it off; `load` is for tests.
+ */
+declare function ensureLocalAgent(root: string, load?: () => Promise<AgentModule>): Promise<void>;
 /** The Pages Router directory and whether it has a custom `_document`, if the app has one. */
 declare function pagesRouterOf(root: string): {
     dir: string;
@@ -44,8 +73,9 @@ declare function liveLoaderScript(live: NonNullable<RevyseNextOptions["live"]>):
     projectKey: string;
 };
 /**
- * Wraps a Next.js config. In `next dev` it adds a JSX loader (webpack and Turbopack) that tags
- * host elements with their source location and loads the Revyse overlay. In every other phase
+ * Wraps a Next.js config. In `next dev` it starts the local agent (L14) and adds a JSX loader
+ * (webpack and Turbopack) that tags host elements with their source location and loads the
+ * Revyse overlay. In every other phase
  * — including `next build` — the config is returned untouched, so nothing ships to production,
  * with one opt-in exception: `live` adds the live overlay's loader tag to production builds.
  */
@@ -53,5 +83,5 @@ declare function withRevyse(config?: ConfigInput, options?: RevyseNextOptions):
     defaultConfig: NextConfig;
 }) => Promise<NextConfig>;
 
-export { DEFAULT_AGENT_PORT, DEFAULT_APP_URL, LOCATIONS_DIR, liveLoaderScript, pagesRouterOf, withRevyse };
-export type { RevyseNextOptions };
+export { DEFAULT_AGENT_PORT, DEFAULT_APP_URL, LOCATIONS_DIR, configuredAgentPort, ensureLocalAgent, liveLoaderScript, pagesRouterOf, withRevyse };
+export type { AgentModule, RevyseNextOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { createRequire } from "module";
 import path from "path";
 var LOCATIONS_DIR = path.join("revyse", "locations");
@@ -8,6 +8,44 @@ var DEFAULT_APP_URL = "https://revyse.dev";
 var PHASE_DEVELOPMENT_SERVER = "phase-development-server";
 var PHASE_PRODUCTION_BUILD = "phase-production-build";
 var require_ = createRequire(import.meta.url);
+function configuredAgentPort(root) {
+  try {
+    const config = JSON.parse(readFileSync(path.join(root, "revyse.config.json"), "utf8"));
+    return typeof config.agentPort === "number" ? config.agentPort : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var say = (msg) => console.log(`[revyse] ${msg}`);
+var warn = (msg) => console.warn(`[revyse] ${msg}`);
+var agentStart;
+function ensureLocalAgent(root, load = () => import("revyse/agent")) {
+  if (process.env.REVYSE_AGENT === "off") return Promise.resolve();
+  agentStart ??= startAgent(root, load).catch(
+    (err) => warn(
+      `Couldn't start Revyse (${err.message}). Check that \`revyse\` is installed as a dev dependency, or run \`npx revyse dev\`.`
+    )
+  );
+  return agentStart;
+}
+async function startAgent(root, load) {
+  if (!existsSync(path.join(root, "revyse.config.json"))) {
+    warn("This app isn't set up for Revyse yet: run `npx revyse init`.");
+    return;
+  }
+  const { startLocalAgent } = await load();
+  const started = await startLocalAgent({ root, log: say });
+  if (started.status === "running") return;
+  if (started.status === "taken") {
+    warn(
+      started.root ? `Port ${started.port} is used by Revyse for ${started.root}, so the overlay here would talk to that project. Set "agentPort" in revyse.config.json to another port, such as ${started.port + 1}.` : `Port ${started.port} is in use by another program. Set "agentPort" in revyse.config.json to a free port.`
+    );
+    return;
+  }
+  say(
+    started.agent.connected ? "Ready: open your app and click the Revyse button." : "Ready, but this project isn't connected to Revyse yet: run `npx revyse init` to connect it."
+  );
+}
 function pagesRouterOf(root) {
   for (const dir of ["pages", "src/pages"]) {
     if (!existsSync(path.join(root, dir))) continue;
@@ -42,7 +80,9 @@ function withRevyse(config = {}, options = {}) {
       return resolved;
     }
     const projectRoot = options.projectRoot ?? process.cwd();
-    const overlayScriptUrl = `http://127.0.0.1:${options.agentPort ?? DEFAULT_AGENT_PORT}/overlay.js`;
+    const agentPort = options.agentPort ?? configuredAgentPort(projectRoot) ?? DEFAULT_AGENT_PORT;
+    const overlayScriptUrl = `http://127.0.0.1:${agentPort}/overlay.js`;
+    void ensureLocalAgent(projectRoot);
     const loader = {
       loader: require_.resolve("@revyse/next/loader"),
       options: { projectRoot, overlayScriptUrl }
@@ -137,6 +177,8 @@ export {
   DEFAULT_AGENT_PORT,
   DEFAULT_APP_URL,
   LOCATIONS_DIR,
+  configuredAgentPort,
+  ensureLocalAgent,
   liveLoaderScript,
   pagesRouterOf,
   withRevyse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revyse/next",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Next.js integration for Revyse: dev-only source locations and overlay injection.",
   "license": "UNLICENSED",
   "repository": {
@@ -38,7 +38,8 @@
   },
   "dependencies": {
     "@babel/parser": "8.0.7",
-    "magic-string": "1.4.3"
+    "magic-string": "1.4.3",
+    "revyse": "0.2.0"
   },
   "devDependencies": {
     "@playwright/test": "~1.56.1",