nuxt-devkit-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lonewolfyx
+
+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/README.md

@@ -0,0 +1,192 @@
+# nuxt-devkit-server
+
+A lightweight Node.js library for creating a local HTTP server that runs Nitro/Nuxt build outputs in CLI tools.
+
+It dynamically imports the Nitro server entry point from a build output directory, wraps it in a `node:http` server, and optionally sets up WebSocket support via `crossws`.
+
+## Installation
+
+```bash
+pnpm add nuxt-devkit-server
+```
+
+If you need WebSocket support, install `crossws` as well:
+
+```bash
+pnpm add crossws
+```
+
+## Usage
+
+### Basic
+
+```ts
+import { createRuntimeServer } from 'nuxt-devkit-server'
+
+const app = await createRuntimeServer({
+    path: '.output',
+})
+
+console.log(`Server running at ${app.url}`) // http://127.0.0.1:7777
+
+// Close the server when done
+await app.close()
+```
+
+### Custom Host and Port
+
+```ts
+const app = await createRuntimeServer({
+    path: '.output/server/index.mjs',
+    host: '0.0.0.0',
+    port: 3000,
+})
+```
+
+### Using the `onReady` Callback
+
+```ts
+const app = await createRuntimeServer({
+    path: 'dist',
+    onReady({ info, app, port }) {
+        console.log(`Listening on ${info.address}:${port}`)
+    },
+})
+```
+
+### Direct Path to Server Entry
+
+You can pass either a Nitro build output directory or a direct path to `server/index.mjs`:
+
+```ts
+// Directory — automatically resolves to <path>/server/index.mjs
+const app = await createRuntimeServer({ path: '.output' })
+
+// Direct file path
+const app = await createRuntimeServer({ path: 'dist/server/index.mjs' })
+```
+
+## API Reference
+
+### `createRuntimeServer(options): Promise<RuntimeServer>`
+
+Creates and starts an HTTP server backed by a Nitro/Nuxt build output.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `options` | `CreateRuntimeServerOptions` | Yes | — | Configuration options |
+
+Returns a `Promise<RuntimeServer>` that resolves once the server is listening.
+
+---
+
+### `CreateRuntimeServerOptions`
+
+```ts
+interface CreateRuntimeServerOptions {
+    /**
+     * Nitro / Nuxt build output directory, or the direct path to server/index.mjs.
+     *
+     * Supported:
+     * - dist
+     * - .output
+     * - dist/server/index.mjs
+     * - .output/server/index.mjs
+     */
+    path: string
+
+    /**
+     * Server port.
+     * Defaults to a dynamic port in the range [7777, 9000].
+     */
+    port?: number
+
+    /**
+     * Server listen address.
+     * Defaults to '127.0.0.1'.
+     */
+    host?: string
+
+    /**
+     * Callback fired once the server is listening.
+     */
+    onReady?: (info: {
+        info: AddressInfo
+        app: RuntimeServer
+        port: number
+    }) => void
+}
+```
+
+### `RuntimeServer`
+
+```ts
+interface RuntimeServer {
+    /** The underlying Node.js HTTP server instance. */
+    server: Server
+
+    /** The full URL of the running server (e.g. http://127.0.0.1:7777). */
+    url: string
+
+    /** Gracefully shuts down the server. */
+    close: () => Promise<void>
+}
+```
+
+### `NitroModule`
+
+The shape of a dynamically imported Nitro server module.
+
+```ts
+interface NitroModule {
+    listener?: unknown
+    middleware?: unknown
+    handler?: unknown
+    default?: unknown
+    websocket?: unknown
+}
+```
+
+The library resolves the HTTP handler in priority order: `listener` > `middleware` > `handler` > `default`.
+
+### `NitroNodeListener`
+
+The type of a Nitro HTTP handler function.
+
+```ts
+type NitroNodeListener = (
+    req: IncomingMessage,
+    res: ServerResponse,
+) => MaybePromise<void>
+```
+
+### `MaybePromise<T>`
+
+A value that may or may not be a promise.
+
+```ts
+type MaybePromise<T> = T | Promise<T>
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development with watch mode
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Lint
+pnpm lint
+
+# Build for production
+pnpm build
+```
+
+## License
+
+[MIT](./LICENSE) &copy; [lonewolfyx](https://github.com/lonewolfyx)

package/dist/index.d.mts

@@ -0,0 +1,51 @@
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { AddressInfo } from "node:net";
+
+//#region src/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type NitroNodeListener = (req: IncomingMessage, res: ServerResponse) => MaybePromise<void>;
+interface NitroModule {
+  listener?: unknown;
+  middleware?: unknown;
+  handler?: unknown;
+  default?: unknown;
+  websocket?: unknown;
+}
+interface CreateRuntimeServerOptions {
+  /**
+   * Nitro / Nuxt build output directory, or the direct path to server/index.mjs.
+   *
+   * Supported:
+   * - dist
+   * - .output
+   * - dist/server/index.mjs
+   * - .output/server/index.mjs
+   */
+  path: string;
+  /**
+   * Server port, defaults to 7777
+   */
+  port?: number;
+  /**
+   * Server listen address, defaults to 127.0.0.1
+   */
+  host?: string;
+  /**
+   * Callback fired once the server is listening.
+   */
+  onReady?: (info: {
+    info: AddressInfo;
+    app: RuntimeServer;
+    port: number;
+  }) => void;
+}
+interface RuntimeServer {
+  server: Server;
+  url: string;
+  close: () => Promise<void>;
+}
+//#endregion
+//#region src/runtime.d.ts
+declare function createRuntimeServer(options: CreateRuntimeServerOptions): Promise<RuntimeServer>;
+//#endregion
+export { type CreateRuntimeServerOptions, type MaybePromise, type NitroModule, type NitroNodeListener, type RuntimeServer, createRuntimeServer };

package/dist/index.mjs

@@ -0,0 +1,88 @@
+import { existsSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getPort } from "get-port-please";
+//#region src/runtime.ts
+function toAbsolutePath(path) {
+	return isAbsolute(path) ? path : resolve(process.cwd(), path);
+}
+function resolveNitroEntry(inputPath) {
+	const absolutePath = toAbsolutePath(inputPath);
+	if (!existsSync(absolutePath)) throw new Error(`Runtime path does not exist: ${absolutePath}`);
+	const entryPath = statSync(absolutePath).isDirectory() ? resolve(absolutePath, "server/index.mjs") : absolutePath;
+	if (!existsSync(entryPath)) throw new Error(`Nitro entry not found: ${entryPath}`);
+	return entryPath;
+}
+function pickNitroListener(mod) {
+	const listener = mod.listener ?? mod.middleware ?? mod.handler ?? mod.default;
+	if (typeof listener !== "function") throw new TypeError("Cannot find a valid Nitro node listener export. Expected one of: listener, middleware, handler, default.");
+	return listener;
+}
+async function loadNitroEntrypoint(path) {
+	const mod = await import(pathToFileURL(resolveNitroEntry(path)).href);
+	return {
+		listener: pickNitroListener(mod),
+		websocket: mod.websocket
+	};
+}
+function listen(server, host, port) {
+	return new Promise((res, rej) => {
+		server.once("error", rej);
+		server.listen(port, host, () => {
+			server.off("error", rej);
+			res(server.address().port);
+		});
+	});
+}
+function closeServer(server) {
+	return new Promise((res, rej) => {
+		server.close((error) => {
+			if (error) {
+				rej(error);
+				return;
+			}
+			res();
+		});
+	});
+}
+async function setupWebSocket(server, websocket) {
+	if (!websocket) return;
+	const { default: nodeAdapter } = await import("crossws/adapters/node");
+	const { handleUpgrade } = nodeAdapter(websocket);
+	server.on("upgrade", (req, socket, head) => {
+		handleUpgrade(req, socket, head);
+	});
+}
+async function createRuntimeServer(options) {
+	const port = options.port ?? await getPort({ portRange: [7777, 9e3] });
+	const host = options.host ?? "127.0.0.1";
+	const nitro = await loadNitroEntrypoint(options.path);
+	const server = createServer(async (req, res) => {
+		try {
+			await nitro.listener(req, res);
+		} catch (error) {
+			if (!res.headersSent) {
+				res.statusCode = 500;
+				res.setHeader("content-type", "text/plain; charset=utf-8");
+			}
+			const message = error instanceof Error ? error.stack ?? error.message : String(error);
+			res.end(message);
+		}
+	});
+	await setupWebSocket(server, nitro.websocket);
+	const actualPort = await listen(server, host, port);
+	const app = {
+		server,
+		url: `http://${host}:${actualPort}`,
+		close: () => closeServer(server)
+	};
+	if (options.onReady) options.onReady({
+		info: server.address(),
+		app,
+		port: actualPort
+	});
+	return app;
+}
+//#endregion
+export { createRuntimeServer };

package/package.json

@@ -0,0 +1,76 @@
+{
+    "name": "nuxt-devkit-server",
+    "type": "module",
+    "version": "0.0.1",
+    "packageManager": "pnpm@10.33.2",
+    "description": "Create a local server for running Nuxt outputs in CLI tools.",
+    "author": "lonewolfyx",
+    "license": "MIT",
+    "homepage": "https://github.com/lonewolfyx/nuxt-devkit-server",
+    "bugs": {
+        "url": "https://github.com/lonewolfyx/nuxt-devkit-server/issues"
+    },
+    "keywords": [
+        "nuxt",
+        "dev",
+        "server"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs"
+        }
+    },
+    "main": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "dev": "tsdown --watch",
+        "build": "tsdown",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "eslint .",
+        "lint:fix": "eslint --fix",
+        "prepare": "simple-git-hooks",
+        "prepublishOnly": "pnpm build"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org",
+        "access": "public"
+    },
+    "peerDependencies": {
+        "crossws": ">=0.4"
+    },
+    "peerDependenciesMeta": {
+        "crossws": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "get-port-please": "^3.2.0"
+    },
+    "devDependencies": {
+        "@antfu/eslint-config": "^9.0.0",
+        "@lonewolfyx/tsconfig": "^0.0.6",
+        "@types/node": "^25.9.1",
+        "crossws": "^0.4.5",
+        "eslint": "^10.4.0",
+        "jiti": "^2.7.0",
+        "nano-staged": "^1.0.2",
+        "picocolors": "^1.1.1",
+        "simple-git-hooks": "^2.13.1",
+        "tsdown": "^0.22.0",
+        "tsx": "^4.22.3",
+        "typescript": "^6.0.3",
+        "vitest": "^4.1.7"
+    },
+    "simple-git-hooks": {
+        "pre-commit": "npx nano-staged",
+        "commit-msg": "node scripts/verify-commit.js"
+    },
+    "nano-staged": {
+        "*": "eslint --fix"
+    }
+}