@fluixi/start 0.1.0-alpha.63 → 0.1.0-alpha.65

package/dist/adapters/platforms.js

@@ -0,0 +1,231 @@
+/**
+ * Deploy adapters for the three hosts that expect a specific output layout.
+ *
+ * Each one bundles the same generated entry and then writes whatever the platform
+ * reads to route a request. What differs is only that layout — the handler, the
+ * dispatch order and the render are shared.
+ *
+ * All three inline the framework: a worker or a serverless function is a file that
+ * gets uploaded, not an install, so nothing may be left to resolve at runtime.
+ */
+import { mkdir, writeFile, readFile, cp, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { readTemplate } from '../adapter.js';
+import { cloudflareEntry, netlifyEntry, vercelEntry } from './entry.js';
+/** What the generated entry needs to know about this build. */
+async function entrySource(ctx, from, prerendered) {
+    const template = await readTemplate(ctx.clientDir, ctx.serverDir);
+    // Written by the build from Vite's SSR manifest; absent for an app with no file routes.
+    const assetFile = join(ctx.serverDir, 'route-assets.json');
+    const routeAssets = existsSync(assetFile) ? JSON.parse(await readFile(assetFile, 'utf-8')) : {};
+    const middleware = join(ctx.serverDir, 'middleware.js');
+    const rel = (file) => {
+        // Node resolves a relative specifier against the importer, and the entry is
+        // written to `from`; keep it POSIX so the bundler reads it the same on Windows.
+        const path = join(ctx.serverDir, file).replace(/\\/g, '/');
+        return path.startsWith('/') ? path : `./${path}`;
+    };
+    return {
+        serverEntry: rel('entry-server.js'),
+        middleware: existsSync(middleware) ? rel('middleware.js') : null,
+        template,
+        ssr: ctx.cfg.ssr,
+        mountId: ctx.cfg.mountId,
+        prerendered,
+        routeAssets,
+    };
+}
+/**
+ * Is `dist/client/index.html` a page, or the shell the server renders into?
+ *
+ * Vite writes the shell at the path a prerendered `/` would occupy, and every one of
+ * these platforms serves a matching file before invoking anything — so `/` is the one
+ * route an SSR app cannot render, and the CDN answers it with an empty mount element.
+ * No other route is affected: nothing exists at `/about` unless it was prerendered.
+ */
+function indexIsPage(template, mountId) {
+    const mount = new RegExp(`<([a-z-]+)[^>]*\\sid=["']${mountId}["'][^>]*>`, 'i').exec(template);
+    if (!mount)
+        return false;
+    return !template.slice(mount.index + mount[0].length).trimStart().startsWith('</');
+}
+/** Nothing to wrap: a fully static SPA has no server entry, and that is not a failure. */
+function skipWhenStatic(ctx, name) {
+    if (ctx.hasServer)
+        return false;
+    console.log(`  fluixi: no server entry — ${name} gets the static output alone.`);
+    return true;
+}
+/**
+ * Add a rule to `_redirects` without taking the file over. Apps ship their own (the
+ * docs site redirects `/` to its default locale), so ours goes last — first match
+ * wins, so the app's rules are reached first.
+ */
+async function appendRedirect(clientDir, rule) {
+    const file = join(clientDir, '_redirects');
+    const existing = await readFile(file, 'utf-8').catch(() => '');
+    if (existing.includes(rule))
+        return;
+    const separator = existing && !existing.endsWith('\n') ? '\n' : '';
+    await writeFile(file, `${existing}${separator}${rule}\n`);
+}
+/**
+ * A SPA routes in the browser, but a cold request for `/settings/profile` finds no
+ * file, so the host has to hand back the shell for anything it cannot match.
+ *
+ * Cloudflare Pages already does this for a project with no `_worker.js` (checked on a
+ * deployed build), so its adapter writes nothing. Netlify and Vercel both 404.
+ */
+const SPA_FALLBACK = '/*  /index.html  200';
+/** Cloudflare caps `_routes.json` at 100 rules. */
+const CF_MAX_RULES = 100;
+/**
+ * The routes a prerendered page is served at, from the HTML on disk.
+ *
+ * `/` is in the list only when `index.html` holds a rendered page rather than the
+ * shell, because that is the difference between a file the platform should serve and
+ * a route the app has to render.
+ */
+async function prerenderedRoutes(dir, mountId) {
+    const out = [];
+    const walk = async (current) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'assets' || entry.name.startsWith('.'))
+                    continue;
+                await walk(path);
+            }
+            else if (entry.name.endsWith('.html')) {
+                const rel = relative(dir, path).replace(/\\/g, '/').replace(/index\.html$/, '').replace(/\.html$/, '');
+                out.push('/' + rel.replace(/\/$/, ''));
+            }
+        }
+    };
+    await walk(dir);
+    const index = await readFile(join(dir, 'index.html'), 'utf-8').catch(() => '');
+    const root = indexIsPage(index, mountId);
+    return out.filter((r) => r !== '/' || root).sort();
+}
+/**
+ * Cloudflare Pages. `_worker.js` at the root of the published directory takes every
+ * request; `_routes.json` is what decides whether a request costs an invocation.
+ *
+ * In advanced mode the worker sees everything not excluded — so a prerendered page
+ * would wake it just to proxy the file back through the ASSETS binding. On a plan
+ * metered by request that is the whole page view budget spent on static files, so
+ * every prerendered path is excluded by name.
+ *
+ * Publish `dist/client`.
+ */
+export const cloudflareAdapter = {
+    name: 'cloudflare',
+    bundle: 'inline',
+    serve({ handler }) {
+        return { fetch: handler };
+    },
+    async build(ctx) {
+        if (skipWhenStatic(ctx, 'cloudflare'))
+            return;
+        const out = join(ctx.clientDir, '_worker.js');
+        const prerendered = await prerenderedRoutes(ctx.clientDir, ctx.cfg.mountId);
+        await ctx.bundleEntry(cloudflareEntry(await entrySource(ctx, out, prerendered)), out);
+        // Everything under /assets is content-hashed and immutable, so it never needs the
+        // worker. `_worker.js` itself must be excluded or Pages would route it to itself.
+        // `/` is excluded only when it was prerendered — otherwise the worker is the only
+        // thing that can answer it, and excluding it would serve the shell instead.
+        const base = ['/assets/*', '/_worker.js'];
+        const room = CF_MAX_RULES - base.length;
+        const exclude = [...base, ...prerendered.slice(0, room)];
+        if (prerendered.length > room) {
+            // Past the cap the remainder still works — it just wakes the worker to hand
+            // back a file. Worth saying, because the symptom is a bill, not an error.
+            console.warn(`  fluixi: ${prerendered.length} prerendered routes exceed Cloudflare's ${CF_MAX_RULES}-rule ` +
+                `limit for _routes.json; ${prerendered.length - room} will invoke the worker to serve a static file.`);
+        }
+        await writeFile(join(ctx.clientDir, '_routes.json'), JSON.stringify({ version: 1, include: ['/*'], exclude }, null, 2) + '\n');
+    },
+};
+/**
+ * Netlify. The function is a v2 fetch handler under `.netlify/functions-internal/`,
+ * which is where a framework — as opposed to the user — puts one, so it cannot
+ * collide with the app's own `netlify/functions`.
+ *
+ * Publish `dist/client`.
+ */
+export const netlifyAdapter = {
+    name: 'netlify',
+    bundle: 'inline',
+    serve({ handler }) {
+        return { fetch: handler };
+    },
+    async build(ctx) {
+        // A SPA has no function to fall back to, so the CDN has to hand back the shell.
+        if (skipWhenStatic(ctx, 'netlify'))
+            return appendRedirect(ctx.clientDir, SPA_FALLBACK);
+        const dir = join(ctx.root, '.netlify', 'functions-internal');
+        await mkdir(dir, { recursive: true });
+        const out = join(dir, 'fluixi-server.mjs');
+        const prerendered = await prerenderedRoutes(ctx.clientDir, ctx.cfg.mountId);
+        await ctx.bundleEntry(netlifyEntry(await entrySource(ctx, out, prerendered)), out);
+        // v2 functions declare their own routing, but the manifest is what makes Netlify
+        // load an internal function at all.
+        await writeFile(join(dir, 'fluixi-server.json'), JSON.stringify({ config: { path: '/*', preferStatic: true }, version: 1 }, null, 2) + '\n');
+        // `preferStatic` is what keeps assets, prerendered pages and files like
+        // `favicon.ico` off the function — and it is also what would hand back the shell
+        // for `/`. A forced redirect is the one exception the CDN honours over a file, so
+        // it claims exactly that path and nothing else. Appended, so an app's own rules in
+        // `public/_redirects` still match first.
+        if (!prerendered.includes('/')) {
+            await appendRedirect(ctx.clientDir, '/  /.netlify/functions/fluixi-server  200!');
+        }
+    },
+};
+/**
+ * Vercel, through the Build Output API v3: `.vercel/output/` is read directly, with
+ * no framework detection and no `vercel.json` to keep in sync.
+ *
+ * `config.json` routes the filesystem first so a prerendered page is served as a
+ * file, then sends the rest to the function.
+ */
+export const vercelAdapter = {
+    name: 'vercel',
+    bundle: 'inline',
+    serve({ handler }) {
+        return { fetch: handler };
+    },
+    async build(ctx) {
+        const output = join(ctx.root, '.vercel', 'output');
+        await mkdir(output, { recursive: true });
+        // Static assets and prerendered HTML are served straight from here.
+        await cp(ctx.clientDir, join(output, 'static'), { recursive: true });
+        if (skipWhenStatic(ctx, 'vercel')) {
+            await writeFile(join(output, 'config.json'), JSON.stringify({
+                version: 3,
+                // The filesystem phase alone answers 404 for a client route, since nothing
+                // is on disk at that path; the catch-all is what makes it a SPA.
+                routes: [{ handle: 'filesystem' }, { src: '/(.*)', dest: '/index.html' }],
+            }, null, 2) + '\n');
+            return;
+        }
+        const fn = join(output, 'functions', 'index.func');
+        await mkdir(fn, { recursive: true });
+        const out = join(fn, 'index.mjs');
+        const prerendered = await prerenderedRoutes(ctx.clientDir, ctx.cfg.mountId);
+        await ctx.bundleEntry(vercelEntry(await entrySource(ctx, out, prerendered)), out);
+        await writeFile(join(fn, '.vc-config.json'), JSON.stringify({ runtime: 'nodejs20.x', handler: 'index.mjs', launcherType: 'Nodejs', shouldAddHelpers: false }, null, 2) + '\n');
+        await writeFile(join(output, 'config.json'), JSON.stringify({
+            version: 3,
+            routes: [
+                // The filesystem holds a shell at `/index.html`, so `/` has to be claimed
+                // before that phase or it is served unrendered. Skipped when `/` really is
+                // a prerendered page, which the filesystem should answer.
+                ...(prerendered.includes('/') ? [] : [{ src: '/', dest: '/index' }]),
+                // A prerendered page or an asset wins; only a miss reaches the function.
+                { handle: 'filesystem' },
+                { src: '/(.*)', dest: '/index' },
+            ],
+        }, null, 2) + '\n');
+    },
+};

package/dist/api.d.ts.map

@@ -1 +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"}
+{"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,CAuC/E;AAED,eAAO,MAAM,kBAAkB,uBAAW,CAAC"}

package/dist/api.js

@@ -90,11 +90,17 @@ export function apiRoutesVitePlugin(opts) {
     const id = '\0' + API_VMOD;
     return {
         name: 'fluixi-api',
+        // Must beat node resolution: '@fluixi/start/api-routes' is a real file in this package,
+        // so without `pre` Vite resolves the typed stub and the generated table never loads —
+        // the app builds and every API route 404s.
+        enforce: 'pre',
         configResolved(config) {
             root = config.root || root;
         },
         resolveId(source) {
-            return source === API_VMOD ? id : null;
+            // The public specifier is a real module so its types ship with the package; both
+            // resolve to the generated table.
+            return source === API_VMOD || source === '@fluixi/start/api-routes' ? id : null;
         },
         load(source) {
             if (source !== id)

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

@@ -1 +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"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,cAAc,CAAC;AAQjE;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFpE"}

package/dist/commands/build.js

@@ -1,7 +1,9 @@
 import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { mkdir, writeFile, rm, copyFile, readFile } from 'node:fs/promises';
+import { resolve, dirname, join, basename } from 'node:path';
 import { resolveConfig } from '../config.js';
 import { fluixiPlugins, loadServerEnv } from '../internal.js';
+import { ssrBuildOptions } from '../adapter.js';
 import { prerender } from './prerender.js';
 import { wordmark, step, done, c } from '../ui.js';
 /**
@@ -15,6 +17,8 @@ export async function build(config = {}) {
     await loadServerEnv(cfg.root, 'production'); // .env → process.env (server-only secrets)
     const { build: viteBuild } = await import('vite');
     const plugins = await fluixiPlugins(cfg);
+    // The deploy target decides whether the framework is bundled in or imported at runtime.
+    const ssr = ssrBuildOptions(cfg);
     process.stdout.write(`\n  ${wordmark()}  ${c.gray('building for production')}\n\n`);
     step('client bundle');
     await viteBuild({
@@ -27,11 +31,11 @@ export async function build(config = {}) {
     // 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');
+        step(`server bundle${bundleNote(cfg)}`);
         await viteBuild({
             root: cfg.root,
             plugins,
-            ssr: { noExternal: cfg.ssrNoExternal.length ? cfg.ssrNoExternal : undefined },
+            ssr,
             build: {
                 outDir: 'dist/server',
                 ssr: serverEntrySrc,
@@ -48,7 +52,7 @@ export async function build(config = {}) {
             root: cfg.root,
             plugins,
             logLevel: 'warn',
-            ssr: { noExternal: cfg.ssrNoExternal.length ? cfg.ssrNoExternal : undefined },
+            ssr,
             build: {
                 outDir: 'dist/server',
                 ssr: middlewareSrc,
@@ -56,12 +60,118 @@ export async function build(config = {}) {
             },
         });
     }
+    await collectRouteAssets(cfg);
     // SSG: prerender routes to static HTML in dist/client (config-driven).
     if (cfg.prerender) {
+        // Prerendering `/` writes over the built `index.html`, and that file is also the
+        // template the server renders into. Keep the shell before it goes: without this a
+        // prerendered home page becomes the template, so every SSR response carries the
+        // home page's markup and head around the app it just rendered.
+        await copyFile(resolve(cfg.root, 'dist/client', 'index.html'), resolve(cfg.root, 'dist/server', 'template.html'));
         process.stdout.write('\n');
         await prerender(config);
     }
+    // The deploy target's own output layout — a worker entry, a function manifest, a
+    // routing config. Last, so everything it wraps or copies already exists.
+    if (cfg.adapter?.build) {
+        step(`${cfg.adapter.name} output`);
+        await cfg.adapter.build({
+            cfg,
+            root: cfg.root,
+            clientDir: resolve(cfg.root, 'dist/client'),
+            serverDir: resolve(cfg.root, 'dist/server'),
+            hasServer: existsSync(resolve(cfg.root, 'dist/server', 'entry-server.js')),
+            bundleEntry: (source, outFile) => bundleEntry(cfg, plugins, source, outFile),
+        });
+    }
     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`);
 }
+/**
+ * Turn Vite's SSR manifest into the map the server needs, and stop publishing the
+ * manifest itself.
+ *
+ * The manifest is keyed by module id and the server only has a path, so the join
+ * happens here: scan the routes the way the plugin does, resolve each to its files,
+ * write a map the runtime can look a URL up in.
+ *
+ * Only routes are kept, and it goes to `dist/server`: `dist/client` is published, and
+ * a full manifest there maps every source path to its chunk for no reader.
+ */
+async function collectRouteAssets(cfg) {
+    const clientDir = resolve(cfg.root, 'dist/client');
+    const manifestFile = join(clientDir, '.vite', 'ssr-manifest.json');
+    if (!existsSync(manifestFile))
+        return;
+    const serverDir = resolve(cfg.root, 'dist/server');
+    const routesDir = resolve(cfg.root, cfg.routesDir);
+    if (existsSync(serverDir) && existsSync(routesDir)) {
+        const manifest = JSON.parse(await readFile(manifestFile, 'utf-8'));
+        const { scanRoutes } = await import('@fluixi/core/plugins');
+        const base = cfg.routesDir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
+        // Keyed by URL pattern: the runtime has a path, and resolving it here leaves it a
+        // lookup and nothing else.
+        const assets = {};
+        const walk = (routes, inherited) => {
+            for (const route of routes) {
+                // A match renders every layer, so layouts fold in here rather than being
+                // unioned per request.
+                const files = [...new Set([...inherited, ...(manifest[`${base}/${route.filePath}`] ?? [])])];
+                if (files.length)
+                    assets[route.urlPath] = [...new Set([...(assets[route.urlPath] ?? []), ...files])];
+                walk(route.children, files);
+            }
+        };
+        walk(scanRoutes(routesDir), []);
+        await writeFile(join(serverDir, 'route-assets.json'), JSON.stringify(assets, null, 2) + '\n');
+    }
+    await rm(join(clientDir, '.vite'), { recursive: true, force: true });
+}
+/**
+ * Bundle a generated platform entry into one self-contained file.
+ *
+ * The entry is written next to its output so a relative import of the server bundle
+ * resolves, then removed — a stray `.fluixi-entry.js` in dist would be served as a
+ * static asset on every one of these platforms.
+ */
+async function bundleEntry(cfg, plugins, source, outFile) {
+    const { build: viteBuild } = await import('vite');
+    const dir = dirname(outFile);
+    const temp = join(dir, `.fluixi-entry-${Date.now()}.js`);
+    await mkdir(dir, { recursive: true });
+    await writeFile(temp, source);
+    try {
+        await viteBuild({
+            root: cfg.root,
+            plugins: plugins,
+            logLevel: 'warn',
+            // Nothing may be left to resolve: these run as an uploaded file, not an install.
+            ssr: { noExternal: true },
+            build: {
+                outDir: dir,
+                emptyOutDir: false,
+                ssr: temp,
+                rollupOptions: {
+                    output: {
+                        entryFileNames: basename(outFile),
+                        // One file, no chunks. A lazy route would otherwise be split out beside
+                        // the entry — and for Cloudflare that directory is the published one, so
+                        // every server chunk would be a public download.
+                        inlineDynamicImports: true,
+                    },
+                },
+            },
+        });
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+/** `server bundle (node · external)` — the output shape is not obvious from the file. */
+function bundleNote(cfg) {
+    const adapter = cfg.adapter;
+    if (!adapter?.bundle)
+        return '';
+    return c.gray(` (${adapter.name} · ${adapter.bundle})`);
+}

package/dist/commands/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The CLI commands.
+ *
+ * Kept off the package root deliberately: these reach the dev server, the build
+ * and the prerenderer, and a module that only wants `defineMiddleware` should not
+ * be able to pull a bundler in behind it. That matters at build time — a deploy
+ * adapter inlines everything the entry can reach, and reaching this would put
+ * vite in a worker.
+ */
+export { dev } from './dev.js';
+export { build } from './build.js';
+export { start } from './start.js';
+export { prerender } from './prerender.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/commands/index.js

@@ -0,0 +1,13 @@
+/**
+ * The CLI commands.
+ *
+ * Kept off the package root deliberately: these reach the dev server, the build
+ * and the prerenderer, and a module that only wants `defineMiddleware` should not
+ * be able to pull a bundler in behind it. That matters at build time — a deploy
+ * adapter inlines everything the entry can reach, and reaching this would put
+ * vite in a worker.
+ */
+export { dev } from './dev.js';
+export { build } from './build.js';
+export { start } from './start.js';
+export { prerender } from './prerender.js';

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

@@ -1 +1 @@
-{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/commands/start.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKjD;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQpE"}
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/commands/start.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKjD;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBpE"}

package/dist/commands/start.js

@@ -14,5 +14,14 @@ export async function start(config = {}) {
     await loadServerEnv(cfg.root, 'production'); // .env → process.env (server-only secrets)
     const clientDir = resolve(cfg.root, 'dist/client');
     const handler = await createProdHandler(cfg);
-    await nodeAdapter.serve({ handler, cfg, clientDir });
+    // The configured adapter, or node when there is none. An adapter that returns
+    // `{ fetch }` has no process to run — its output is a module the platform imports —
+    // so say that instead of exiting as if the server had started.
+    const adapter = cfg.adapter ?? nodeAdapter;
+    const served = await adapter.serve({ handler, cfg, clientDir });
+    if (served && typeof served === 'object' && 'fetch' in served) {
+        console.log(`  fluixi: the "${adapter.name}" adapter exports a fetch handler — there is no server ` +
+            `to start. Deploy dist/ and let the platform invoke it, or run \`fluixi start\` with ` +
+            `a filesystem adapter (nodeAdapter).`);
+    }
 }

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { Adapter } from './adapter.js';
 /**
  * Fluixi app config. Place in `fluixi.config.{ts,js,mjs}` at the app root and wrap
  * with `defineConfig` for types. Everything is optional — the defaults match the
@@ -31,6 +32,12 @@ export interface FluixiConfig {
     middleware?: string;
     /** SSR deps Vite must bundle (no-external) — e.g. ESM packages without file extensions. */
     ssrNoExternal?: string[];
+    /**
+     * Deploy target. Decides how `fluixi build` bundles the server (see the adapter's
+     * `bundle` mode) and how `fluixi start` serves it. Unset keeps Vite's own bundling
+     * heuristic and serves with `nodeAdapter`.
+     */
+    adapter?: Adapter;
     /**
      * Built-in i18n auto-discovery. Scans `<dir>/<locale>.json` and exposes them as
      * `virtual:fluixi-i18n` (`{ messages, locales, defaultLocale }`) to feed `createI18n`.
@@ -64,10 +71,12 @@ export interface ResolvedPrerender {
     routes: string[];
     crawl: boolean;
 }
-export type ResolvedConfig = Required<Omit<FluixiConfig, 'ssrNoExternal' | 'i18n' | 'prerender'>> & {
+export type ResolvedConfig = Required<Omit<FluixiConfig, 'ssrNoExternal' | 'i18n' | 'prerender' | 'adapter'>> & {
     ssrNoExternal: string[];
     i18n: ResolvedI18n | false;
     prerender: ResolvedPrerender | false;
+    /** Stays optional: no adapter means "Vite's defaults + serve with node". */
+    adapter?: Adapter;
 };
 /** Identity helper for editor types in `fluixi.config.ts`. */
 export declare function defineConfig(config: FluixiConfig): FluixiConfig;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6GAA6G;IAC7G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9E;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9D;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC,GAAG;IAClG,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,YAAY,GAAG,KAAK,CAAC;IAC3B,SAAS,EAAE,iBAAiB,GAAG,KAAK,CAAC;CACtC,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D;AAED,sBAAsB;AACtB,wBAAgB,aAAa,CAAC,MAAM,GAAE,YAAiB,GAAG,cAAc,CAiBvE;AAgCD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,SAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAM5E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6GAA6G;IAC7G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9E;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9D;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,CACnC,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC,CACvE,GAAG;IACF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,YAAY,GAAG,KAAK,CAAC;IAC3B,SAAS,EAAE,iBAAiB,GAAG,KAAK,CAAC;IACrC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D;AAED,sBAAsB;AACtB,wBAAgB,aAAa,CAAC,MAAM,GAAE,YAAiB,GAAG,cAAc,CAkBvE;AAgCD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,SAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAM5E"}

package/dist/config.js

@@ -21,6 +21,7 @@ export function resolveConfig(config = {}) {
         apiDir: config.apiDir ?? 'src/api',
         middleware: config.middleware ?? 'src/middleware.ts',
         ssrNoExternal: config.ssrNoExternal ?? [],
+        adapter: config.adapter,
         i18n: resolveI18n(config.i18n),
         prerender: resolvePrerender(config.prerender),
     };

package/dist/document.d.ts

@@ -0,0 +1,41 @@
+import type { FetchHandler } from './handler.js';
+/**
+ * Inject server-rendered app HTML into the template's mount element
+ * (`<div id="root"></div>`). Falls back to a `<!--ssr-outlet-->` marker, then to
+ * just before `</body>`.
+ */
+export declare function injectApp(template: string, appHtml: string, mountId?: string): string;
+/**
+ * Split the template at the mount point for streaming: `head` is everything up to and
+ * including the open mount tag (flushed first so the browser fetches assets while the
+ * server awaits data); `tail` is the close tag onward (client script + `</body>`).
+ * Mirrors injectApp's three cases (mount div, `<!--ssr-outlet-->`, before `</body>`).
+ */
+export declare function splitTemplate(template: string, mountId?: string): {
+    head: string;
+    tail: string;
+};
+/**
+ * Reference the files this route needs in the document that renders it.
+ *
+ * A lazily-imported route is its own chunk with its own stylesheet, mentioned nowhere
+ * in the shell — without these the browser discovers them when hydration runs the
+ * dynamic import, so the markup paints before the CSS arrives.
+ *
+ * Files already named in the template are skipped: the entry chunk is in there from
+ * the client build, and preloading it again competes with the request in flight.
+ */
+export declare function injectPreload(template: string, files: string[]): string;
+/**
+ * Inject the rendered app into the mount point AND lift any @fluixi/head metadata (carried back as
+ * a marker by renderRequestAsync) into <head> + <html>. If the page set a title, the template's own
+ * <title> is dropped so there's only one. No marker → identical to injectApp.
+ */
+export declare function injectAppAndHead(template: string, rendered: string, mountId?: string): string;
+/**
+ * Wrap a fetch handler so a thrown/rejected error becomes a 500 instead of an
+ * unhandled rejection. `createRequestHandler` already guards the renderer; this
+ * covers the middleware chain that wraps it. `onError` lets dev map the stack first.
+ */
+export declare function guardHandler(handler: FetchHandler, onError?: (e: unknown) => void): FetchHandler;
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CASrF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwBhG;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAevE;AASD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAW7F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,GAC7B,YAAY,CAYd"}