@devframes/next 0.7.14

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+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/dist/client.d.mts

@@ -0,0 +1,62 @@
+import { DevframeConnectionStatus, DevframeRpcClient } from "devframe/client";
+import { ReactNode } from "react";
+import { ConnectionMeta } from "devframe/types";
+//#region src/client.d.ts
+interface DevframeRpcState {
+  /** The connected client, or `null` while the initial connect is in flight. */
+  rpc: DevframeRpcClient | null;
+  /** Live connection status — `'connecting'` until the client resolves. */
+  status: DevframeConnectionStatus;
+  /** The latest connection error, or `null`. */
+  error: Error | null;
+}
+interface RpcProviderProps {
+  children: ReactNode;
+  /**
+   * Base URL the SPA discovers `__connection.json` under, relative to the
+   * running page. Defaults to `'./'` (resolved against `document.baseURI`), so
+   * a devframe mounted at `/__<id>/` connects without extra configuration.
+   */
+  baseURL?: string;
+  /**
+   * Pre-resolved connection meta. Pass this to skip the `__connection.json`
+   * fetch entirely (e.g. when the host already knows the WS endpoint).
+   */
+  connectionMeta?: ConnectionMeta;
+}
+/**
+ * Connect to the devframe RPC backend once and provide the client — plus live
+ * connection status — to the tree. The React counterpart to `@devframes/nuxt`'s
+ * client plugin.
+ *
+ * Children render immediately (before the connection resolves), so your shell
+ * and a connection indicator stay visible throughout; read the client with
+ * {@link useRpc} and the status with {@link useRpcStatus}.
+ *
+ * ```tsx
+ * 'use client'
+ * import { RpcProvider } from '@devframes/next/client'
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   return <RpcProvider baseURL="/__my-tool/">{children}</RpcProvider>
+ * }
+ * ```
+ */
+declare function RpcProvider({ children, baseURL, connectionMeta }: RpcProviderProps): ReactNode;
+/**
+ * Read the connected {@link DevframeRpcClient}, or `null` while connecting.
+ * Scope it to your tool's RPC namespace with `useRpc()?.scope('my-tool:')`.
+ *
+ * Throws when called outside a `<RpcProvider>`.
+ */
+declare function useRpc(): DevframeRpcClient | null;
+/**
+ * Read the live connection `status` and latest `error`, for a connection
+ * indicator. Throws when called outside a `<RpcProvider>`.
+ */
+declare function useRpcStatus(): {
+  status: DevframeConnectionStatus;
+  error: Error | null;
+};
+//#endregion
+export { DevframeRpcState, RpcProvider, RpcProviderProps, useRpc, useRpcStatus };

package/dist/client.mjs

@@ -0,0 +1,95 @@
+"use client";
+import { connectDevframe } from "devframe/client";
+import { createContext, useContext, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/client.tsx
+const RpcContext = createContext(null);
+const INITIAL = {
+	rpc: null,
+	status: "connecting",
+	error: null
+};
+/**
+* Connect to the devframe RPC backend once and provide the client — plus live
+* connection status — to the tree. The React counterpart to `@devframes/nuxt`'s
+* client plugin.
+*
+* Children render immediately (before the connection resolves), so your shell
+* and a connection indicator stay visible throughout; read the client with
+* {@link useRpc} and the status with {@link useRpcStatus}.
+*
+* ```tsx
+* 'use client'
+* import { RpcProvider } from '@devframes/next/client'
+*
+* export function Providers({ children }: { children: React.ReactNode }) {
+*   return <RpcProvider baseURL="/__my-tool/">{children}</RpcProvider>
+* }
+* ```
+*/
+function RpcProvider({ children, baseURL = "./", connectionMeta }) {
+	const [state, setState] = useState(INITIAL);
+	useEffect(() => {
+		let active = true;
+		let client;
+		const sync = () => {
+			if (active && client) setState({
+				rpc: client,
+				status: client.status,
+				error: client.connectionError
+			});
+		};
+		const offs = [];
+		connectDevframe({
+			baseURL,
+			connectionMeta
+		}).then((c) => {
+			if (!active) return;
+			client = c;
+			sync();
+			offs.push(c.events.on("connection:status", sync));
+			offs.push(c.events.on("connection:error", sync));
+		}, (err) => {
+			if (active) setState({
+				rpc: null,
+				status: "error",
+				error: err instanceof Error ? err : new Error(String(err))
+			});
+		});
+		return () => {
+			active = false;
+			for (const off of offs) off();
+		};
+	}, [baseURL]);
+	return /* @__PURE__ */ jsx(RpcContext.Provider, {
+		value: state,
+		children
+	});
+}
+function useDevframeState() {
+	const state = useContext(RpcContext);
+	if (!state) throw new Error("[@devframes/next] useRpc()/useRpcStatus() must be called inside a <RpcProvider>.");
+	return state;
+}
+/**
+* Read the connected {@link DevframeRpcClient}, or `null` while connecting.
+* Scope it to your tool's RPC namespace with `useRpc()?.scope('my-tool:')`.
+*
+* Throws when called outside a `<RpcProvider>`.
+*/
+function useRpc() {
+	return useDevframeState().rpc;
+}
+/**
+* Read the live connection `status` and latest `error`, for a connection
+* indicator. Throws when called outside a `<RpcProvider>`.
+*/
+function useRpcStatus() {
+	const { status, error } = useDevframeState();
+	return {
+		status,
+		error
+	};
+}
+//#endregion
+export { RpcProvider, useRpc, useRpcStatus };

package/dist/index.d.mts

@@ -0,0 +1,173 @@
+import { CreateDevServerOptions } from "devframe/adapters/dev";
+import { ConnectionMeta, DevframeDefinition, DevframeHost, DevframeStorageScope } from "devframe/types";
+//#region src/config.d.ts
+/**
+ * Minimal shape of the bits of `next.config` this helper reads/writes, so the
+ * package doesn't pull Next's full config type graph into its `.d.ts` bundle.
+ * Any real `NextConfig` structurally satisfies it.
+ */
+interface DevframeNextConfig {
+  skipTrailingSlashRedirect?: boolean;
+  [key: string]: unknown;
+}
+/**
+ * Apply the Next config settings a devframe **host** requires, preserving
+ * everything else.
+ *
+ * Sets `skipTrailingSlashRedirect: true`: mounted devframe SPAs are served at
+ * `/__<id>/` and reference their assets relatively (`./_next/…`). Next's
+ * default trailing-slash redirect (`/__git/` → `/__git`) would re-root those
+ * relative paths and 404 every asset, leaving the panel unstyled and unable to
+ * connect. Serving the base path verbatim keeps relative resolution intact.
+ *
+ * ```js [next.config.mjs]
+ * import { withDevframe } from '@devframes/next'
+ *
+ * export default withDevframe({
+ *   // ...your own Next config
+ * })
+ * ```
+ */
+declare function withDevframe<T extends DevframeNextConfig>(nextConfig?: T): T;
+//#endregion
+//#region src/handler.d.ts
+interface CreateDevframeNextHandlerOptions {
+  /**
+   * Mount base for the SPA. Defaults to `def.basePath ?? '/__<id>/'` — the
+   * hosted-adapter default, so the devframe shares the Next app's origin
+   * without colliding with its routes.
+   */
+  base?: string;
+  /** Bind host for the side-car RPC/WS server. Default: `def.cli?.host ?? 'localhost'`. */
+  host?: string;
+  /** Pin the side-car port. Default: resolved from `def.cli?.port` via `get-port-please`. */
+  port?: number;
+  /** Flag bag forwarded to `def.setup(ctx, { flags })`. */
+  flags?: Record<string, unknown>;
+  /**
+   * Whether the side-car runs its own auth gate. Defaults to `false`: this is a
+   * hosted adapter and the Next app owns authentication. Pass `true` for
+   * devframe's interactive gate or a handler for a custom scheme.
+   */
+  auth?: CreateDevServerOptions['auth'];
+  /** Origin the Next app is reachable at, for docks needing an absolute URL. */
+  resolveOrigin?: () => string;
+  /** Override where persisted devframe state lives (defaults under the cwd / home). */
+  getStorageDir?: (scope: DevframeStorageScope) => string;
+  /**
+   * Expose the side-car's route-based MCP server (Streamable-HTTP) and
+   * advertise it in the handler's `__connection.json`. Forwarded to
+   * `createDevServer`: overrides `def.cli?.mcp`, `undefined` falls through to
+   * it, `false` disables the route regardless. The endpoint lives on the
+   * side-car's own port, so the advertised meta carries `{ port, path }`.
+   *
+   * @experimental
+   */
+  mcp?: CreateDevServerOptions['mcp'];
+}
+interface DevframeNextHandler {
+  /**
+   * WHATWG-`fetch` handler for the catch-all App Router route. Serves the
+   * plugin's built SPA at `base` and answers `<base>/__connection.json` with
+   * the side-car WS endpoint. Awaits {@link DevframeNextHandler.ready} so the
+   * first request doesn't race the server boot.
+   */
+  fetch: (request: Request) => Promise<Response>;
+  /** Resolves once the side-car RPC/WS server is listening. */
+  ready: Promise<void>;
+  /** Shut the side-car server down (call from an app-lifecycle hook / test). */
+  close: () => Promise<void>;
+}
+/**
+ * Host a **single** devframe from a Next.js App Router app — the convenience
+ * wrapper over {@link createDevframeNextHost} for the common case of mounting
+ * one plugin (the Next counterpart to `viteDevBridge`'s bridge mode).
+ *
+ * It statically serves `def.cli.distDir` at `base` through the Next route and
+ * starts a side-car RPC/WS dev server (via `createDevServer` in bridge mode) on
+ * its own port, advertising that endpoint at `<base>/__connection.json` so the
+ * SPA's `connectDevframe()` can dial back in.
+ *
+ * ```ts [app/__my-tool/[[...path]]/route.ts]
+ * import myDevframe from '@/devframe'
+ * import { createDevframeNextHandler } from '@devframes/next'
+ *
+ * export const runtime = 'nodejs'
+ * export const dynamic = 'force-dynamic'
+ *
+ * const handler = createDevframeNextHandler(myDevframe)
+ * export const GET = handler.fetch
+ * ```
+ *
+ * For a hub hosting many devframes at once, use {@link createDevframeNextHost}
+ * directly with `@devframes/hub`.
+ */
+declare function createDevframeNextHandler(def: DevframeDefinition, options?: CreateDevframeNextHandlerOptions): DevframeNextHandler;
+//#endregion
+//#region src/host.d.ts
+interface CreateDevframeNextHostOptions {
+  /**
+   * Public origin the Next app is reachable at, e.g. `http://localhost:3000`.
+   * Surfaced through {@link DevframeHost.resolveOrigin} for docks that need an
+   * absolute iframe URL.
+   */
+  resolveOrigin: () => string;
+  /**
+   * Resolve a directory the host owns for persisted devframe state, per
+   * {@link DevframeHost.getStorageDir}.
+   */
+  getStorageDir: (scope: DevframeStorageScope) => string;
+  /**
+   * Initial connection meta served at every base registered via
+   * {@link DevframeHost.mountConnectionMeta}. Usually unknown until the
+   * side-car RPC/WS server has started — publish it later with
+   * {@link DevframeNextHost.setConnectionMeta}.
+   */
+  connectionMeta?: ConnectionMeta;
+}
+interface DevframeNextHost {
+  /**
+   * The {@link DevframeHost} to hand to `createHubContext` / `createHostContext`.
+   * Its `mountStatic` / `mountConnectionMeta` calls accumulate into the
+   * {@link DevframeNextHost.fetch} handler below.
+   */
+  host: DevframeHost;
+  /**
+   * A WHATWG-`fetch` handler that serves every mounted SPA (with SPA
+   * fallback, correct content types, and path-traversal guarding — all from
+   * devframe's own `serveStaticHandler`) and answers `<base>/__connection.json`
+   * for each base registered via `mountConnectionMeta`. Delegate a Next App
+   * Router route handler straight to it:
+   *
+   * ```ts
+   * export async function GET(request: Request) {
+   *   return (await ensureHub()).fetch(request)
+   * }
+   * ```
+   */
+  fetch: (request: Request) => Promise<Response>;
+  /**
+   * Publish the live connection meta once the RPC/WS server is up. Until this
+   * is called (and without an initial `connectionMeta`), meta requests answer
+   * `503` so a racing client retries rather than caching a wrong endpoint.
+   */
+  setConnectionMeta: (meta: ConnectionMeta) => void;
+}
+/**
+ * Build a Node-runtime {@link DevframeHost} for a Next.js App Router app that
+ * hosts one or more devframes, plus the single `fetch` handler its catch-all
+ * route delegates to.
+ *
+ * This is the hosted-adapter counterpart to `viteDevBridge` for the Next
+ * runtime, which — being webpack/Turbopack rather than Vite — can't reuse the
+ * Vite middleware path. Instead of hand-rolling static serving in a route
+ * handler, static mounts are registered on an internal h3 app and served
+ * through devframe's shared `serveStaticHandler` (`app.fetch` makes h3 a
+ * WHATWG-`fetch` handler, exactly what an App Router route returns).
+ *
+ * Pins Node runtime (`export const runtime = 'nodejs'` in the route) because
+ * the static handler streams from the filesystem.
+ */
+declare function createDevframeNextHost(options: CreateDevframeNextHostOptions): DevframeNextHost;
+//#endregion
+export { type CreateDevframeNextHandlerOptions, type CreateDevframeNextHostOptions, type DevframeNextConfig, type DevframeNextHandler, type DevframeNextHost, createDevframeNextHandler, createDevframeNextHost, withDevframe };

package/dist/index.mjs

@@ -0,0 +1,170 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta } from "devframe/adapters/dev";
+import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_WS_ROUTE } from "devframe/constants";
+import { serveStaticHandler } from "devframe/utils/serve-static";
+import { H3 } from "h3";
+//#region src/config.ts
+/**
+* Apply the Next config settings a devframe **host** requires, preserving
+* everything else.
+*
+* Sets `skipTrailingSlashRedirect: true`: mounted devframe SPAs are served at
+* `/__<id>/` and reference their assets relatively (`./_next/…`). Next's
+* default trailing-slash redirect (`/__git/` → `/__git`) would re-root those
+* relative paths and 404 every asset, leaving the panel unstyled and unable to
+* connect. Serving the base path verbatim keeps relative resolution intact.
+*
+* ```js [next.config.mjs]
+* import { withDevframe } from '@devframes/next'
+*
+* export default withDevframe({
+*   // ...your own Next config
+* })
+* ```
+*/
+function withDevframe(nextConfig = {}) {
+	return {
+		...nextConfig,
+		skipTrailingSlashRedirect: nextConfig.skipTrailingSlashRedirect ?? true
+	};
+}
+//#endregion
+//#region src/host.ts
+const META_SUFFIX = `/${DEVFRAME_CONNECTION_META_FILENAME}`;
+/** Drop trailing slashes from a mount base (`/__git/` → `/__git`). */
+function stripTrailingSlash(base) {
+	return base.replace(/\/+$/, "");
+}
+/**
+* Build a Node-runtime {@link DevframeHost} for a Next.js App Router app that
+* hosts one or more devframes, plus the single `fetch` handler its catch-all
+* route delegates to.
+*
+* This is the hosted-adapter counterpart to `viteDevBridge` for the Next
+* runtime, which — being webpack/Turbopack rather than Vite — can't reuse the
+* Vite middleware path. Instead of hand-rolling static serving in a route
+* handler, static mounts are registered on an internal h3 app and served
+* through devframe's shared `serveStaticHandler` (`app.fetch` makes h3 a
+* WHATWG-`fetch` handler, exactly what an App Router route returns).
+*
+* Pins Node runtime (`export const runtime = 'nodejs'` in the route) because
+* the static handler streams from the filesystem.
+*/
+function createDevframeNextHost(options) {
+	const app = new H3();
+	const metaBases = /* @__PURE__ */ new Set();
+	let connectionMeta = options.connectionMeta;
+	const host = {
+		mountStatic(base, distDir) {
+			const staticApp = new H3();
+			staticApp.use(serveStaticHandler(distDir));
+			app.mount(stripTrailingSlash(base), staticApp);
+		},
+		mountConnectionMeta(base) {
+			metaBases.add(stripTrailingSlash(base));
+		},
+		resolveOrigin: options.resolveOrigin,
+		getStorageDir: options.getStorageDir
+	};
+	async function fetch(request) {
+		const { pathname } = new URL(request.url);
+		if (pathname.endsWith(META_SUFFIX) && metaBases.has(pathname.slice(0, -META_SUFFIX.length))) {
+			if (!connectionMeta) return new Response(null, { status: 503 });
+			return Response.json(connectionMeta);
+		}
+		const response = await app.fetch(request);
+		if (response.status === 404) return new Response(null, { status: 404 });
+		return response;
+	}
+	return {
+		host,
+		fetch,
+		setConnectionMeta(meta) {
+			connectionMeta = meta;
+		}
+	};
+}
+//#endregion
+//#region src/handler.ts
+/** Ensure a mount base has a single leading and trailing slash. */
+function normalizeBase(base) {
+	return `/${base}/`.replace(/\/{2,}/g, "/");
+}
+function defaultGetStorageDir(scope) {
+	const cwd = process.cwd();
+	if (scope === "workspace") return join(cwd, ".devframe");
+	if (scope === "project") return join(cwd, "node_modules/.devframe");
+	return join(homedir(), ".devframe");
+}
+/**
+* Host a **single** devframe from a Next.js App Router app — the convenience
+* wrapper over {@link createDevframeNextHost} for the common case of mounting
+* one plugin (the Next counterpart to `viteDevBridge`'s bridge mode).
+*
+* It statically serves `def.cli.distDir` at `base` through the Next route and
+* starts a side-car RPC/WS dev server (via `createDevServer` in bridge mode) on
+* its own port, advertising that endpoint at `<base>/__connection.json` so the
+* SPA's `connectDevframe()` can dial back in.
+*
+* ```ts [app/__my-tool/[[...path]]/route.ts]
+* import myDevframe from '@/devframe'
+* import { createDevframeNextHandler } from '@devframes/next'
+*
+* export const runtime = 'nodejs'
+* export const dynamic = 'force-dynamic'
+*
+* const handler = createDevframeNextHandler(myDevframe)
+* export const GET = handler.fetch
+* ```
+*
+* For a hub hosting many devframes at once, use {@link createDevframeNextHost}
+* directly with `@devframes/hub`.
+*/
+function createDevframeNextHandler(def, options = {}) {
+	const distDir = def.cli?.distDir;
+	if (!distDir) throw new Error(`[@devframes/next] createDevframeNextHandler("${def.id}") needs a built SPA to serve, but "cli.distDir" is not set on the devframe definition.`);
+	const base = normalizeBase(options.base ?? def.basePath ?? `/__${def.id}/`);
+	const hostName = options.host ?? def.cli?.host;
+	const nextHost = createDevframeNextHost({
+		resolveOrigin: options.resolveOrigin ?? (() => ""),
+		getStorageDir: options.getStorageDir ?? defaultGetStorageDir
+	});
+	nextHost.host.mountStatic(base, distDir);
+	nextHost.host.mountConnectionMeta?.(base);
+	let started;
+	const ready = (async () => {
+		const port = options.port ?? await resolveDevServerPort(def, { host: hostName });
+		started = await createDevServer(def, {
+			host: hostName,
+			port,
+			flags: options.flags,
+			openBrowser: false,
+			auth: options.auth ?? false,
+			mcp: options.mcp
+		});
+		const mcpMeta = resolveMcpConnectionMeta(def, options.mcp, port);
+		nextHost.setConnectionMeta({
+			backend: "websocket",
+			websocket: {
+				port,
+				path: `/${DEVFRAME_WS_ROUTE}`
+			},
+			...mcpMeta ? { mcp: mcpMeta } : {}
+		});
+	})();
+	return {
+		async fetch(request) {
+			await ready;
+			return nextHost.fetch(request);
+		},
+		ready,
+		async close() {
+			await ready.catch(() => {});
+			await started?.close();
+		}
+	};
+}
+//#endregion
+export { createDevframeNextHandler, createDevframeNextHost, withDevframe };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@devframes/next",
+  "type": "module",
+  "version": "0.7.14",
+  "description": "Next.js host integration for Devframe — serve mounted devframe SPAs and connection meta from an App Router route (experimental)",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "packages/next",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devframe",
+    "next",
+    "nextjs",
+    "devtools"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.mts",
+      "default": "./dist/client.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "devframe": "0.7.14"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "h3": "^2.0.1-rc.22"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.17",
+    "react": "^19.2.8",
+    "tsdown": "^0.22.14",
+    "devframe": "0.7.14"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}