@fluixi/start 0.1.0-alpha.43

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluixi
+
+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,101 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/fluixi/assets/main/logos/128x128.png" alt="Fluixi" width="120" height="120" />
+</p>
+
+# @fluixi/start
+
+**The Fluixi meta-framework — zero-config dev/build/start with SSR, file routing, and hydration.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](./LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)
+![Registry](https://img.shields.io/badge/registry-GitHub%20Packages-181717?logo=github)
+![Vite](https://img.shields.io/badge/built%20on-Vite-646cff?logo=vite&logoColor=white)
+
+---
+
+## ✨ Overview
+
+`@fluixi/start` is `dev`, `build`, and production `start` over [`@fluixi/server`](../server)
++ Vite, so apps stop hand-rolling a `server.mjs`. This package is the **runtime**
+(programmatic commands + config); the `fluixi` CLI lives in [`@fluixi/cli`](../cli), and
+you scaffold a new app with [`create-fluixi`](../create) (`npm create fluixi`).
+
+```bash
+fluixi dev      # SSR dev server (Vite middleware + HMR)
+fluixi build    # client + server bundles → dist/client, dist/server
+fluixi start    # production SSR server (after build)
+```
+
+## 📦 Installation
+
+```ini
+# .npmrc
+@fluixi:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+```sh
+pnpm add @fluixi/start @fluixi/cli
+```
+
+## 🗂️ Conventions
+
+| Default | Config key |
+| --- | --- |
+| `src/entry-server.ts` exporting `render(url)` (and optionally `renderStream(url)`) | `serverEntry` |
+| `src/entry-client.ts` (hydration) | `clientEntry` |
+| `src/routes/` (file-based routes → `virtual:fluixi-routes`) | `routesDir` |
+| `src/middleware.ts` (optional request middleware) | `middleware` |
+| `index.html` with `<div id="root"></div>` | `template` / `mountId` |
+| port `3000` | `port` |
+
+## ⚙️ Config
+
+`fluixi.config.{ts,mts,mjs,js}` — TypeScript configs are bundled on the fly:
+
+```ts
+import { defineConfig } from '@fluixi/start/config';
+
+export default defineConfig({
+  port: 3010,
+  ssrNoExternal: ['@medusajs/js-sdk'], // SSR deps Vite must bundle
+});
+```
+
+## 🚀 Features
+
+- **Streaming SSR** — export `renderStream(url)` (via `@fluixi/server`'s
+  `renderToBodyStream`) and the `index.html` head is flushed first, then the app body is
+  streamed into the mount point.
+- **Middleware / guards** — `src/middleware.ts` default-exports `defineMiddleware([...])`,
+  a `(request, next) => Response` chain run before SSR (auth redirects, headers, …).
+- **Server functions** — a `"use server"` function runs only on the server and is callable
+  from the client over RPC (`/_server`, same-origin CSRF); `getRequestEvent()` works inside
+  it.
+- **Routing** — `@fluixi/start/router` re-exports [`@fluixi/core/router-next`](../core):
+  `Router`, `Outlet`, `Link`, `Form`, the hooks, `createMemoryHistory`.
+- **Deploy adapters** — `createProdHandler` builds a runtime-neutral fetch handler;
+  `nodeAdapter` (Node http + static files) and `webAdapter` (`export { fetch }` for
+  edge/worker) serve it. The same handler runs on Node, Bun, Deno, and edge runtimes.
+
+## 🧰 Programmatic
+
+```js
+import { dev, build, start, createProdHandler } from '@fluixi/start';
+
+await dev({ port: 3010 });                 // or build() / start()
+const handler = await createProdHandler();  // a (Request) => Promise<Response>
+```
+
+## 🔌 Subpaths
+
+| Import | What |
+| --- | --- |
+| `@fluixi/start` | `dev`/`build`/`start`, the fetch-handler layer, adapters, middleware helpers |
+| `@fluixi/start/config` | `defineConfig`, `loadConfig`, `resolveConfig` |
+| `@fluixi/start/router` | the routing surface (re-export of `@fluixi/core/router-next`) |
+| `@fluixi/start/server-fn` | server-function runtime (`isServerFnRequest`, `handleServerFn`) |
+
+## 📄 License
+
+[MIT](./LICENSE) © [Fluixi](https://fluixi.dev)

package/dist/adapter.d.ts

@@ -0,0 +1,32 @@
+import type { FluixiConfig, ResolvedConfig } from './config.js';
+import { type FetchHandler } from './handler.js';
+/**
+ * Build the production SSR fetch handler from a `fluixi build` output (dist/server +
+ * dist/client/index.html). It's runtime-neutral — the SAME handler runs on Node, Bun,
+ * Deno, and edge/worker runtimes. Adapters decide how to serve it + assets.
+ */
+export declare function createProdHandler(config?: FluixiConfig): Promise<FetchHandler>;
+export interface AdapterContext {
+    handler: FetchHandler;
+    cfg: ResolvedConfig;
+    /** Built client assets dir (dist/client). */
+    clientDir: string;
+}
+/**
+ * A deploy target. The runtime-neutral fetch handler is the portable core; an adapter
+ * packages it for a platform: filesystem runtimes (node) listen on a port and serve
+ * static files from disk; edge/serverless runtimes return a `{ fetch }` export the
+ * platform invokes (assets served by the platform/CDN). Build-time artifact emission
+ * (worker bundle, function manifest) is a later increment.
+ */
+export interface Adapter {
+    name: string;
+    serve(ctx: AdapterContext): Promise<void> | {
+        fetch: FetchHandler;
+    };
+}
+/** Reference filesystem adapter — Node `http` + static files from dist/client. */
+export declare const nodeAdapter: Adapter;
+/** Reference edge/web adapter — export `{ fetch }`; the platform serves assets. */
+export declare const webAdapter: Adapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAGtB;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAkDxF;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,EAAE,cAAc,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG;QAAE,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC;CACrE;AAED,kFAAkF;AAClF,eAAO,MAAM,WAAW,EAAE,OAQzB,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,UAAU,EAAE,OAKxB,CAAC"}

package/dist/adapter.js

@@ -0,0 +1,78 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveConfig } from './config.js';
+import { injectAppAndHead, splitTemplate, guardHandler } from './internal.js';
+import { createRequestHandler, serveNode, streamDocument, withStaticFiles, } from './handler.js';
+import { composeMiddleware, normalizeMiddleware } from './middleware.js';
+/**
+ * Build the production SSR fetch handler from a `fluixi build` output (dist/server +
+ * dist/client/index.html). It's runtime-neutral — the SAME handler runs on Node, Bun,
+ * Deno, and edge/worker runtimes. Adapters decide how to serve it + assets.
+ */
+export async function createProdHandler(config = {}) {
+    const cfg = resolveConfig(config);
+    const clientDir = resolve(cfg.root, 'dist/client');
+    const template = await readFile(join(clientDir, 'index.html'), 'utf-8');
+    const serverEntry = resolve(cfg.root, 'dist/server', 'entry-server.js');
+    // SPA apps may ship no server entry (or one only for server functions) — import if present.
+    const mod = existsSync(serverEntry)
+        ? await import(/* @vite-ignore */ pathToFileURL(serverEntry).href)
+        : {};
+    // Streaming when the entry exports `renderStream` (a body stream): flush the split
+    // template head first, pipe the body, then the tail. Else inject the string render.
+    let core;
+    if (!cfg.ssr) {
+        // SPA: the page is the static shell; the client entry renders it. Server functions +
+        // middleware still run through this handler — there's just no SSR render pass.
+        core = createRequestHandler(async () => template);
+    }
+    else if (typeof mod.renderStream === 'function') {
+        const { head, tail } = splitTemplate(template, cfg.mountId);
+        core = async (request) => {
+            const url = new URL(request.url);
+            const body = await mod.renderStream(url.pathname + url.search, request);
+            return streamDocument(head, body, tail);
+        };
+    }
+    else {
+        const render = mod.render ?? mod.default;
+        core = createRequestHandler(async (url, request) => injectAppAndHead(template, await render(url, request), cfg.mountId));
+    }
+    // Server-function RPC dispatch. The entry-server module re-exports the dispatcher, so
+    // it shares the registry that the app's "use server" modules populated (a separate
+    // node-imported copy would have an empty registry).
+    if (typeof mod.handleServerFn === 'function' && typeof mod.isServerFnRequest === 'function') {
+        const render = core;
+        core = (request) => (mod.isServerFnRequest(request) ? mod.handleServerFn(request) : render(request));
+    }
+    // File-based API routes — the entry-server re-exports them from virtual:fluixi-api.
+    if (typeof mod.handleApiRequest === 'function' && typeof mod.isApiRequest === 'function') {
+        const next = core;
+        core = (request) => (mod.isApiRequest(request) ? mod.handleApiRequest(request) : next(request));
+    }
+    // Optional request middleware (src/middleware.ts → dist/server/middleware.js).
+    const mwFile = resolve(cfg.root, 'dist/server', 'middleware.js');
+    if (!existsSync(mwFile))
+        return guardHandler(core);
+    const mwMod = await import(/* @vite-ignore */ pathToFileURL(mwFile).href);
+    return guardHandler(composeMiddleware(normalizeMiddleware(mwMod), core));
+}
+/** Reference filesystem adapter — Node `http` + static files from dist/client. */
+export const nodeAdapter = {
+    name: 'node',
+    async serve({ handler, cfg, clientDir }) {
+        serveNode(withStaticFiles(handler, clientDir), {
+            port: cfg.port,
+            onListen: (p) => console.log(`  fluixi start (node) → http://localhost:${p}`),
+        });
+    },
+};
+/** Reference edge/web adapter — export `{ fetch }`; the platform serves assets. */
+export const webAdapter = {
+    name: 'web',
+    serve({ handler }) {
+        return { fetch: handler };
+    },
+};

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+export interface ApiRoute {
+    /** Regex source matching the pathname. */
+    source: string;
+    /** Param names, in capture-group order. */
+    keys: string[];
+    /** The route module (its method exports). */
+    mod: Record<string, unknown>;
+    /** Higher = more specific (static beats dynamic beats catch-all). */
+    rank: number;
+}
+/** Derive a route pattern from a file path relative to the api dir (no extension). */
+export declare function derivePattern(rel: string, prefix?: string): {
+    source: string;
+    keys: string[];
+    rank: number;
+};
+/** Whether a pathname falls under the api prefix (so a miss 404s as API, not SSR). */
+export declare function isApiPath(pathname: string, prefix?: string): boolean;
+/** First matching route (by rank) for a pathname, with decoded params. */
+export declare function matchApiRoutes(routes: ApiRoute[], pathname: string): {
+    mod: Record<string, unknown>;
+    params: Record<string, string>;
+} | null;
+/** Match + invoke the method handler. 404 outside any route, 405 when the method is missing. */
+export declare function handleApi(routes: ApiRoute[], request: Request, prefix?: string): Promise<Response>;
+/**
+ * Scan `dir` for API route files → `virtual:fluixi-api` exporting `isApiRequest(request)` +
+ * `handleApiRequest(request)`. Files are statically imported so they bundle for prod.
+ */
+export declare function apiRoutesVitePlugin(opts: {
+    dir: string;
+    prefix?: string;
+}): any;
+export declare const API_VIRTUAL_MODULE = "virtual:fluixi-api";
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAS,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqB5G;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,GAAG,OAAO,CAEpE;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAS5I;AAED,gGAAgG;AAChG,wBAAsB,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAYxG;AAkBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,CAiC/E;AAED,eAAO,MAAM,kBAAkB,uBAAW,CAAC"}

package/dist/api.js

@@ -0,0 +1,120 @@
+// File-based API routes. Files under `apiDir` (default src/api) export HTTP-method handlers
+// (GET/POST/PUT/PATCH/DELETE) that take (request, { params }) and return a Web Response. They map
+// to `/api/<path>` ([id] → param, [...rest] → catch-all). A scan plugin emits `virtual:fluixi-api`
+// (isApiRequest + handleApiRequest); dev auto-wires it, prod gets it via the entry-server re-export.
+import { readdirSync, statSync } from 'node:fs';
+import { resolve as resolvePath, relative as relativePath, join } from 'node:path';
+const API_VMOD = 'virtual:fluixi-api';
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
+/** Derive a route pattern from a file path relative to the api dir (no extension). */
+export function derivePattern(rel, prefix = '/api') {
+    const segs = rel.split('/').filter(Boolean);
+    if (segs[segs.length - 1] === 'index')
+        segs.pop();
+    const keys = [];
+    let rank = 0;
+    const parts = segs.map((seg) => {
+        const catchAll = seg.match(/^\[\.\.\.(.+)\]$/);
+        if (catchAll) {
+            keys.push(catchAll[1]);
+            return '(.+)';
+        }
+        const param = seg.match(/^\[(.+)\]$/);
+        if (param) {
+            keys.push(param[1]);
+            rank += 1;
+            return '([^/]+)';
+        }
+        rank += 10;
+        return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    });
+    return { source: `^${prefix}${parts.length ? '/' + parts.join('/') : ''}/?$`, keys, rank };
+}
+/** Whether a pathname falls under the api prefix (so a miss 404s as API, not SSR). */
+export function isApiPath(pathname, prefix = '/api') {
+    return pathname === prefix || pathname.startsWith(prefix + '/');
+}
+/** First matching route (by rank) for a pathname, with decoded params. */
+export function matchApiRoutes(routes, pathname) {
+    for (const r of [...routes].sort((a, b) => b.rank - a.rank)) {
+        const m = new RegExp(r.source).exec(pathname);
+        if (!m)
+            continue;
+        const params = {};
+        r.keys.forEach((k, i) => (params[k] = decodeURIComponent(m[i + 1] ?? '')));
+        return { mod: r.mod, params };
+    }
+    return null;
+}
+/** Match + invoke the method handler. 404 outside any route, 405 when the method is missing. */
+export async function handleApi(routes, request, prefix = '/api') {
+    const pathname = new URL(request.url).pathname;
+    const match = matchApiRoutes(routes, pathname);
+    if (!match)
+        return new Response('Not Found', { status: 404 });
+    const fn = match.mod[request.method];
+    if (typeof fn !== 'function') {
+        const allow = METHODS.filter((m) => typeof match.mod[m] === 'function').join(', ');
+        return new Response('Method Not Allowed', { status: 405, headers: allow ? { allow } : undefined });
+    }
+    const out = await fn(request, { params: match.params });
+    if (out instanceof Response)
+        return out;
+    return new Response(JSON.stringify(out ?? null), { headers: { 'content-type': 'application/json; charset=utf-8' } });
+}
+function scanFiles(dir, base = dir) {
+    let out = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        const full = join(dir, name);
+        if (statSync(full).isDirectory())
+            out = out.concat(scanFiles(full, base));
+        else if (/\.(ts|tsx|js|mjs)$/.test(name) && !/\.(spec|test)\./.test(name))
+            out.push(full);
+    }
+    return out;
+}
+/**
+ * Scan `dir` for API route files → `virtual:fluixi-api` exporting `isApiRequest(request)` +
+ * `handleApiRequest(request)`. Files are statically imported so they bundle for prod.
+ */
+export function apiRoutesVitePlugin(opts) {
+    let root = process.cwd();
+    const prefix = opts.prefix ?? '/api';
+    const id = '\0' + API_VMOD;
+    return {
+        name: 'fluixi-api',
+        configResolved(config) {
+            root = config.root || root;
+        },
+        resolveId(source) {
+            return source === API_VMOD ? id : null;
+        },
+        load(source) {
+            if (source !== id)
+                return null;
+            const dir = resolvePath(root, opts.dir);
+            const files = scanFiles(dir);
+            const imports = [];
+            const entries = [];
+            files.forEach((file, i) => {
+                const rel = relativePath(dir, file).replace(/\.(ts|tsx|js|mjs)$/, '').split(/[\\/]/).join('/');
+                const { source: src, keys, rank } = derivePattern(rel, prefix);
+                imports.push(`import * as _${i} from ${JSON.stringify(file)};`);
+                entries.push(`{ source: ${JSON.stringify(src)}, keys: ${JSON.stringify(keys)}, rank: ${rank}, mod: _${i} }`);
+            });
+            return (`import { isApiPath, handleApi } from '@fluixi/start/api';\n` +
+                `${imports.join('\n')}\n` +
+                `const routes = [${entries.join(',')}];\n` +
+                `export const isApiRequest = (request) => isApiPath(new URL(request.url).pathname, ${JSON.stringify(prefix)});\n` +
+                `export const handleApiRequest = (request) => handleApi(routes, request, ${JSON.stringify(prefix)});\n`);
+        },
+    };
+}
+export const API_VIRTUAL_MODULE = API_VMOD;

package/dist/commands/build.d.ts

@@ -0,0 +1,8 @@
+import type { FluixiConfig } from '../config.js';
+/**
+ * Production build: a client bundle (browser, with an SSR manifest) and a server
+ * bundle (the entry that renders HTML). @fluixi/start provides the fluixi plugins
+ * (file routing + JSX/SSR transform), so the app's vite.config keeps only app bits.
+ */
+export declare function build(config?: FluixiConfig): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMjD;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DpE"}

package/dist/commands/build.js

@@ -0,0 +1,67 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveConfig } from '../config.js';
+import { fluixiPlugins, loadServerEnv } from '../internal.js';
+import { prerender } from './prerender.js';
+import { wordmark, step, done, c } from '../ui.js';
+/**
+ * Production build: a client bundle (browser, with an SSR manifest) and a server
+ * bundle (the entry that renders HTML). @fluixi/start provides the fluixi plugins
+ * (file routing + JSX/SSR transform), so the app's vite.config keeps only app bits.
+ */
+export async function build(config = {}) {
+    const startedAt = Date.now();
+    const cfg = resolveConfig(config);
+    await loadServerEnv(cfg.root, 'production'); // .env → process.env (server-only secrets)
+    const { build: viteBuild } = await import('vite');
+    const plugins = await fluixiPlugins(cfg);
+    process.stdout.write(`\n  ${wordmark()}  ${c.gray('building for production')}\n\n`);
+    step('client bundle');
+    await viteBuild({
+        root: cfg.root,
+        plugins,
+        logLevel: 'warn',
+        build: { outDir: 'dist/client', ssrManifest: true, emptyOutDir: true },
+    });
+    // SSR builds a server bundle that renders HTML. A SPA may still ship one — only for server
+    // functions / middleware — so build it when the entry exists; a pure static SPA skips it.
+    const serverEntrySrc = resolve(cfg.root, cfg.serverEntry);
+    if (cfg.ssr || existsSync(serverEntrySrc)) {
+        step('server bundle');
+        await viteBuild({
+            root: cfg.root,
+            plugins,
+            ssr: { noExternal: cfg.ssrNoExternal.length ? cfg.ssrNoExternal : undefined },
+            build: {
+                outDir: 'dist/server',
+                ssr: serverEntrySrc,
+                emptyOutDir: true,
+            },
+        });
+    }
+    // Optional request middleware → its own server entry (emptyOutDir:false keeps
+    // entry-server.js). createProdHandler picks up dist/server/middleware.js if present.
+    const middlewareSrc = resolve(cfg.root, cfg.middleware);
+    if (existsSync(middlewareSrc)) {
+        step('middleware');
+        await viteBuild({
+            root: cfg.root,
+            plugins,
+            logLevel: 'warn',
+            ssr: { noExternal: cfg.ssrNoExternal.length ? cfg.ssrNoExternal : undefined },
+            build: {
+                outDir: 'dist/server',
+                ssr: middlewareSrc,
+                emptyOutDir: false,
+            },
+        });
+    }
+    // SSG: prerender routes to static HTML in dist/client (config-driven).
+    if (cfg.prerender) {
+        process.stdout.write('\n');
+        await prerender(config);
+    }
+    const ms = Date.now() - startedAt;
+    process.stdout.write('\n');
+    done(`${c.bold('built')} in ${c.bold(String(ms))} ms  ${c.gray('→ dist/client + dist/server')}\n`);
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,8 @@
+import type { FluixiConfig } from '../config.js';
+/**
+ * Dev server: Vite in middleware mode compiles the app on the fly; the server
+ * entry renders the shell per request, injected into the template; the client
+ * entry hydrates. Generalizes the hand-rolled server.mjs pattern.
+ */
+export declare function dev(config?: FluixiConfig): Promise<void>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAQjD;;;;GAIG;AACH,wBAAsB,GAAG,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+ElE"}

package/dist/commands/dev.js

@@ -0,0 +1,91 @@
+import { createServer as createHttp } from 'node:http';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveConfig } from '../config.js';
+import { injectAppAndHead, splitTemplate, installCrashGuards, fluixiPlugins, guardHandler, loadServerEnv, SERVER_FNS_VMOD } from '../internal.js';
+import { toNodeHandler, streamDocument } from '../handler.js';
+import { composeMiddleware, normalizeMiddleware } from '../middleware.js';
+import { isApiPath, API_VIRTUAL_MODULE } from '../api.js';
+import { devReady } from '../ui.js';
+/**
+ * Dev server: Vite in middleware mode compiles the app on the fly; the server
+ * entry renders the shell per request, injected into the template; the client
+ * entry hydrates. Generalizes the hand-rolled server.mjs pattern.
+ */
+export async function dev(config = {}) {
+    const startedAt = Date.now();
+    const cfg = resolveConfig(config);
+    installCrashGuards();
+    await loadServerEnv(cfg.root, 'development'); // .env → process.env (server-only secrets)
+    const { createServer } = await import('vite');
+    const template = readFileSync(resolve(cfg.root, cfg.template), 'utf-8');
+    // Create the HTTP server FIRST so Vite's HMR WebSocket attaches to it instead of
+    // opening its own port (which, if held by a zombie, loops "[vite] server
+    // connection lost" → reload forever). Sharing one port avoids that.
+    let vite;
+    // App render → a runtime-neutral fetch handler. In dev, "render" is Vite
+    // ssrLoadModule + transformIndexHtml; the same handler shape powers prod + adapters.
+    // If the entry exports `renderStream`, stream: transform+split the template, flush
+    // the head, pipe the body stream, then the tail. guardHandler maps pre-flush errors
+    // (a streaming error after the head is out can only truncate the response).
+    const renderHandler = guardHandler(async (request) => {
+        const url = new URL(request.url);
+        const path = url.pathname + url.search;
+        // Server-function RPC: auto-wired. Load the registry vmod (registers every "use server"
+        // fn + wires the request-context runner + re-exports the dispatcher) and route /_server
+        // through it — no need for the app's entry-server to re-export anything.
+        if (url.pathname === '/_server') {
+            const sf = await vite.ssrLoadModule(SERVER_FNS_VMOD);
+            if (sf.isServerFnRequest(request))
+                return sf.handleServerFn(request);
+        }
+        // File-based API routes (src/api/** → /api/*) — auto-wired, no entry change needed.
+        if (isApiPath(url.pathname)) {
+            const api = await vite.ssrLoadModule(API_VIRTUAL_MODULE);
+            if (api.isApiRequest(request))
+                return api.handleApiRequest(request);
+        }
+        // SPA mode: serve the static shell; the client entry renders. The server still ran
+        // (server functions above + middleware below), there's just no SSR render pass.
+        if (!cfg.ssr) {
+            const html = await vite.transformIndexHtml(path, template);
+            return new Response(html, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' } });
+        }
+        const mod = await vite.ssrLoadModule('/' + cfg.serverEntry);
+        if (typeof mod.renderStream === 'function') {
+            const shell = await vite.transformIndexHtml(path, template);
+            const { head, tail } = splitTemplate(shell, cfg.mountId);
+            return streamDocument(head, await mod.renderStream(path, request), tail);
+        }
+        const render = mod.render ?? mod.default;
+        const appHtml = await render(path, request); // sync or async; request enables the locals bridge
+        // injectAppAndHead (not injectApp): lift the @fluixi/head marker renderRequestAsync prepends to
+        // the body into <head> + <html>, exactly like the prod adapter/prerender. Plain injectApp left
+        // the `<!--fh:…-->` marker as the mount root's first child, which stranded the hydration cursor
+        // (whole tree rebuilt → duplicated) AND skipped dev SEO. No marker → identical to injectApp.
+        const html = await vite.transformIndexHtml(path, injectAppAndHead(template, appHtml, cfg.mountId));
+        return new Response(html, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' } });
+    }, (e) => vite.ssrFixStacktrace?.(e));
+    // Optional request middleware. Loaded per request via ssrLoadModule so edits hot-
+    // reload (no server restart); guardHandler turns a middleware throw into a 500.
+    const hasMiddleware = existsSync(resolve(cfg.root, cfg.middleware));
+    const handler = hasMiddleware
+        ? guardHandler(async (request) => {
+            const mwMod = await vite.ssrLoadModule('/' + cfg.middleware);
+            return composeMiddleware(normalizeMiddleware(mwMod), renderHandler)(request);
+        }, (e) => vite.ssrFixStacktrace?.(e))
+        : renderHandler;
+    const nodeHandler = toNodeHandler(handler);
+    const http = createHttp((req, res) => {
+        // Vite middleware first (static assets + HMR), then our handler for app routes.
+        vite.middlewares(req, res, () => nodeHandler(req, res));
+    });
+    vite = await createServer({
+        root: cfg.root,
+        plugins: await fluixiPlugins(cfg), // file routing + JSX/SSR transform (fluixi)
+        server: { middlewareMode: true, hmr: { server: http } },
+        appType: 'custom',
+        ssr: cfg.ssrNoExternal.length ? { noExternal: cfg.ssrNoExternal } : undefined,
+    });
+    http.listen(cfg.port, () => devReady({ port: cfg.port, startedAt }));
+}

package/dist/commands/prerender.d.ts

@@ -0,0 +1,11 @@
+import type { FluixiConfig } from '../config.js';
+export declare function htmlPath(url: string): string;
+export declare function extractLinks(html: string): string[];
+/**
+ * Render routes to static HTML in dist/client, via the real prod handler — so each page is
+ * byte-identical to what `fluixi start` would serve (assets, __FX_DATA__, hydration), it just
+ * lives on disk. Seeds from `prerender.routes` (default `/`) and, when `crawl`, follows internal
+ * links. Returns the written route paths.
+ */
+export declare function prerender(config?: FluixiConfig): Promise<string[]>;
+//# sourceMappingURL=prerender.d.ts.map

package/dist/commands/prerender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerender.d.ts","sourceRoot":"","sources":["../../src/commands/prerender.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMjD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5C;AAGD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQnD;AAOD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA8C5E"}