filesystem-routing 0.3.1 → 0.4.1

package/README.md

@@ -165,7 +165,8 @@ pages get:
 
 Dispatch ships as fetch-style middleware — `filesystem-routing/api` matches
 requests against the manifest's handler refs and composes into any
-`(request, next)` chain, an SSR handler's middleware option included:
+`(request, next)` or `(event, next)` chain, an SSR handler's middleware option
+(`@solidjs/vite-plugin`'s `start.middleware`) included:
 
 ```ts
 // src/middleware.ts
@@ -175,7 +176,8 @@ import { createAPIHandler } from "filesystem-routing/api";
 export default [createAPIHandler(routes)];
 ```
 
-Handlers receive the request event of the surrounding scope (the storage
+Handlers receive the event the chain passes in or, in a `(request, next)`
+chain, the request event of the surrounding scope (the storage
 `provideRequestEvent` establishes — pass `getEvent` to dispatch outside
 one), with the matched `params` written onto it. Unmatched requests (no
 route, or no handler for the method) advance the chain; `HEAD` falls back
@@ -190,6 +192,50 @@ server environment's router only (SolidStart pairs it with `components:
 false` in SPA mode, so the server manifest routes requests without shipping
 page modules) — see the per-environment `routers` option below.
 
+## Server-function pages
+
+With `serverComponents: true`, a page whose default export begins with a
+`"use server"` directive is a server-function page:
+
+```tsx
+// src/routes/stories/[id].tsx
+export const route = { live: true }; // any config the emission adapter reads
+
+export default async function Story({ params }) {
+  "use server";
+  const story = await db.stories.get(params.id);
+  return props => <article>{story.title}{props.children}</article>;
+}
+```
+
+The scanner sees the directive (on an inline function declaration or
+expression, or a top-level function the default export names — not through
+a wrapper call or a re-export) and records two neutral facts on the entry:
+`server: true`, and a `$component` ref marked `eager` and picking only
+`default`. The client side of such a module is a stub, so there is no code
+worth a chunk: the Vite adapter delivers the ref eagerly (`{ src, require }`)
+even with code splitting on, and it is not a build input. What a
+server-rendered page *means* — how the stub is called, cached, and mounted —
+is the emission adapter's business; the scanner only states the fact.
+
+Adapters that carry code only server pages need gate it on
+`filesystem-routing/flags`:
+
+```ts
+import { serverRoutes } from "filesystem-routing/flags";
+import * as server from "./server.js"; // dropped from builds with no server page
+
+if (serverRoutes && entry.server) server.wrap(entry);
+```
+
+The package ships `flags` as a real module whose facts are all `true` — the
+safe answer wherever no plugin hook is in the loop (dev prebundling, a
+hand-built manifest, another bundler). In builds the Vite plugin serves the
+scan's answer instead, folded to a literal, so a gated static import
+tree-shakes out of every app without a server page and is an ordinary
+static import — present at hydration — in every app with one. The option is
+off by default; a manifest built without it is byte-identical to before.
+
 ## Custom conventions
 
 Conventions plug in at two independent seams, so a custom scheme picks the
@@ -310,6 +356,7 @@ fileRoutes({
 | --- | --- |
 | `httpMethods` | emit `$GET`, `$POST`, … refs for uppercase handler exports; a module with handlers but no default export routes without being a page |
 | `components` | set `false` to route without emitting `$component` refs, keeping page modules out of that environment's bundle |
+| `serverComponents` | recognize server-function pages: a `"use server"` default export is flagged `server: true` and delivered eagerly; scan facts are served from `filesystem-routing/flags` (defaults to `false`) |
 | `buildInputs` | environments whose build takes every code-split route module as an entry |
 | `codeSplitting` | set `false` to deliver every module ref as an eager static import — no `lazy()` components, zero dynamic imports, one bundle — for small apps where per-chunk overhead outweighs the split (defaults to `true`; with `@solidjs/router` requires the next release, newer than `2.0.0-next.14`) |
 | `moduleId` | the id the manifest is served from |

package/dist/analyze.d.ts

@@ -8,6 +8,17 @@ export type { StaticExportEntry };
  * a compiler that already performs export analysis can provide it instead.
  */
 export declare function analyzeModule(src: string): StaticExportEntry[];
+export interface RouteModuleAnalysis {
+    exports: StaticExportEntry[];
+    /**
+     * The directive prologue of the default export, when it is a function
+     * declared in this module (inline, or a top-level binding it names):
+     * `"use server"` marks a page whose component runs on the server.
+     */
+    defaultDirective?: string;
+}
+/** `analyzeModule` plus what the default export's function body declares. */
+export declare function analyzeRouteModule(src: string): RouteModuleAnalysis;
 export declare function getExportName(entry: StaticExportEntry): string;
 /**
  * Returns the export name only when it is backed by a same-named local

package/dist/analyze.js

@@ -24,6 +24,10 @@ function loadTsrxParser(src) {
  * a compiler that already performs export analysis can provide it instead.
  */
 export function analyzeModule(src) {
+    return analyzeRouteModule(src).exports;
+}
+/** `analyzeModule` plus what the default export's function body declares. */
+export function analyzeRouteModule(src) {
     const source = fs.readFileSync(src, "utf-8");
     let result;
     if (src.endsWith(".tsrx")) {
@@ -44,7 +48,30 @@ export function analyzeModule(src) {
     const error = result.errors[0];
     if (error)
         throw new SyntaxError(`Failed to parse ${src}:\n${error.codeframe || error.message}`);
-    return result.module.staticExports.flatMap(({ entries }) => entries.filter(entry => !entry.isType && entry.exportName.kind !== "None"));
+    return {
+        exports: result.module.staticExports.flatMap(({ entries }) => entries.filter(entry => !entry.isType && entry.exportName.kind !== "None")),
+        defaultDirective: defaultDirectiveOf(result.program.body)
+    };
+}
+function defaultDirectiveOf(body) {
+    let fn = body.find(node => node.type === "ExportDefaultDeclaration")?.declaration;
+    if (fn?.type === "Identifier") {
+        // `export default Story` — follow the name to a top-level function.
+        const name = fn.name;
+        fn = undefined;
+        for (const node of body) {
+            if (node.type === "FunctionDeclaration" && node.id?.name === name)
+                fn = node;
+            else if (node.type === "VariableDeclaration")
+                for (const d of node.declarations)
+                    if (d.id?.name === name)
+                        fn = d.init;
+        }
+    }
+    if (!fn || !/Function(Declaration|Expression)$/.test(fn.type))
+        return;
+    const first = fn.body?.body?.[0];
+    return first?.type === "ExpressionStatement" ? first.directive : undefined;
 }
 export function getExportName(entry) {
     return entry.exportName.name ?? "default";

package/dist/api.d.ts

@@ -1,9 +1,9 @@
 /**
  * The API dispatch adapter: matches requests against the flat manifest's
  * handler refs (`$GET`, `$POST`, …) and serves them as fetch-style
- * middleware, so API routes compose into any `(request, next)` chain — an
- * SSR handler's middleware option, a framework's request pipeline — with no
- * bundler or server involvement.
+ * middleware, so API routes compose into any `(request, next)` or
+ * `(event, next)` chain — an SSR handler's middleware option, a framework's
+ * request pipeline — with no bundler or server involvement.
  *
  * Ported from SolidStart's `server/routes.ts` (the radix3 matcher) and the
  * method dispatch in its `server/handler.ts`.
@@ -69,7 +69,8 @@ export interface APIHandlerOptions {
     base?: string;
     /**
      * How the adapter reaches the request event it hands to handlers. Defaults
-     * to the core request-event scope (the storage `provideRequestEvent`
+     * to the event the chain passes in or, when it passes a bare `Request`, to
+     * the core request-event scope (the storage `provideRequestEvent`
      * establishes), which is where a middleware chain runs — override it when
      * dispatching outside one, or to hand handlers a richer event.
      */
@@ -85,12 +86,18 @@ export interface APIHandlerOptions {
  * export default [createAPIHandler(routes)];
  * ```
  *
+ * The first argument is the request or a request event carrying it
+ * (`event.request`), so the handler fits `(request, next)` and
+ * `(event, next)` chains alike; it calls `next()` without arguments.
+ *
  * Dispatch preserves SolidStart's semantics: unmatched requests (no route,
  * or no handler for the method) advance the chain; `HEAD` falls back to the
  * `GET` handler; matched params are written to `event.params` before the
  * handler runs. A handler returning `undefined` declines the request —
- * allowed for `GET` only (anything else throws): a page module falls
+ * allowed for `GET` and `HEAD` only (anything else throws): a page module falls
  * through to the chain (its component renders instead), a handler-only
  * module answers 404.
  */
-export declare function createAPIHandler(routes: readonly FileRouteHandlers[], options?: APIHandlerOptions): (request: Request, next: (request?: Request) => Response | Promise<Response>) => Promise<Response>;
+export declare function createAPIHandler(routes: readonly FileRouteHandlers[], options?: APIHandlerOptions): (input: Request | {
+    request: Request;
+}, next: (request?: Request) => Response | Promise<Response>) => Promise<Response>;

package/dist/api.js

@@ -62,8 +62,8 @@ const RequestContext = Symbol.for("solid.RequestContext");
 function getScopedEvent() {
     const event = globalThis[RequestContext]?.getStore();
     if (!event) {
-        throw new Error("API route dispatched outside a request-event scope. Compose the handler " +
-            "inside `provideRequestEvent` (any `ssr.middleware`-style chain already is), " +
+        throw new Error("API route dispatched outside a request-event scope. Pass the request event " +
+            "instead of the request, compose the handler inside `provideRequestEvent`, " +
             "or pass `getEvent`.");
     }
     return event;
@@ -85,18 +85,22 @@ function toResponse(result) {
  * export default [createAPIHandler(routes)];
  * ```
  *
+ * The first argument is the request or a request event carrying it
+ * (`event.request`), so the handler fits `(request, next)` and
+ * `(event, next)` chains alike; it calls `next()` without arguments.
+ *
  * Dispatch preserves SolidStart's semantics: unmatched requests (no route,
  * or no handler for the method) advance the chain; `HEAD` falls back to the
  * `GET` handler; matched params are written to `event.params` before the
  * handler runs. A handler returning `undefined` declines the request —
- * allowed for `GET` only (anything else throws): a page module falls
+ * allowed for `GET` and `HEAD` only (anything else throws): a page module falls
  * through to the chain (its component renders instead), a handler-only
  * module answers 404.
  */
 export function createAPIHandler(routes, options = {}) {
     const match = createAPIMatcher(routes);
-    const getEvent = options.getEvent ?? getScopedEvent;
-    return async (request, next) => {
+    return async (input, next) => {
+        const request = "request" in input ? input.request : input;
         const url = new URL(request.url);
         const matched = match(stripPathBase(url.pathname, options.base ?? "/"), request.method);
         if (!matched)
@@ -105,12 +109,12 @@ export function createAPIHandler(routes, options = {}) {
         const fn = request.method === "HEAD" ? mod.HEAD || mod.GET : mod[request.method];
         if (typeof fn !== "function")
             return next();
-        const event = getEvent();
+        const event = options.getEvent?.() ?? ("request" in input ? input : getScopedEvent());
         event.params = matched.params || {};
         const result = await fn(event);
         if (result !== undefined)
             return toResponse(result);
-        if (request.method !== "GET") {
+        if (request.method !== "GET" && request.method !== "HEAD") {
             throw new Error(`API handler for ${request.method} "${request.url}" did not return a response.`);
         }
         if (!matched.isPage)

package/dist/convention.d.ts

@@ -30,6 +30,14 @@ export interface PageFileSystemRouterConfig extends FileSystemRouterConfig {
      * Pass `true` for the standard set. Defaults to `false`.
      */
     httpMethods?: boolean | readonly string[];
+    /**
+     * Recognize server-function pages: a default export whose body begins with
+     * a `"use server"` directive is flagged `server: true` and its `$component`
+     * delivered eagerly — the client side of such a module is a stub, not a
+     * chunk's worth of component. What a server-rendered page means is the
+     * emission adapter's business. Defaults to `false`.
+     */
+    serverComponents?: boolean;
 }
 /**
  * The module convention proven by SolidStart: a route module is a page when

package/dist/convention.js

@@ -1,4 +1,4 @@
-import { analyzeModule, getExportName, getLocalExportName } from "./analyze.js";
+import { analyzeRouteModule, getExportName, getLocalExportName } from "./analyze.js";
 import { BaseFileSystemRouter, cleanPath } from "./router.js";
 /**
  * The filename convention proven by SolidStart:
@@ -85,24 +85,31 @@ export class PageFileSystemRouter extends BaseFileSystemRouter {
             };
         }
         const methods = httpMethodsOf(this.config);
-        const exports = analyzeModule(src);
+        const { exports, defaultDirective } = analyzeRouteModule(src);
         const exportNames = exports.map(getExportName);
         const localExportNames = exports.map(getLocalExportName).filter(name => name !== undefined);
         const hasDefault = exportNames.includes("default");
         const hasRouteConfig = exportNames.includes("route");
         const handlers = createHandlerRefs(src, exportNames, methods);
         const hasHandlers = Object.keys(handlers).length > 0;
+        // A server-function page (opt-in): the client gets a stub, not a chunk's
+        // worth of component, so it is delivered eagerly and flagged for the adapter.
+        const server = this.config.serverComponents === true && hasDefault && defaultDirective === "use server";
         if (hasDefault || hasHandlers) {
             return {
                 page: hasDefault,
+                ...(server ? { server } : {}),
                 $component: components && hasDefault
                     ? {
                         src: src,
-                        pick: [
-                            ...localExportNames.filter(name => name !== "route" && !methods.includes(name)),
-                            "default",
-                            "$css"
-                        ]
+                        pick: server
+                            ? ["default"]
+                            : [
+                                ...localExportNames.filter(name => name !== "route" && !methods.includes(name)),
+                                "default",
+                                "$css"
+                            ],
+                        ...(server ? { eager: true } : {})
                     }
                     : undefined,
                 $$route: hasRouteConfig

package/dist/flags.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Facts about the route scan, for emission adapters to gate static imports
+ * on. This file is the fallback: every fact is `true`, so code that reads it
+ * without the Vite plugin in the loop (dev prebundling, a hand-built
+ * manifest, another bundler) errs toward "present", never toward "broken".
+ * `filesystem-routing/vite` replaces this module in builds with the scan's
+ * actual answers, folded to literals, so an adapter's
+ * `if (serverRoutes) use(server)` drops its import when no route needs it.
+ */
+/** `true` when some page's component is a server function (`server: true`). */
+export declare const serverRoutes: boolean;

package/dist/flags.js

@@ -0,0 +1,11 @@
+/**
+ * Facts about the route scan, for emission adapters to gate static imports
+ * on. This file is the fallback: every fact is `true`, so code that reads it
+ * without the Vite plugin in the loop (dev prebundling, a hand-built
+ * manifest, another bundler) errs toward "present", never toward "broken".
+ * `filesystem-routing/vite` replaces this module in builds with the scan's
+ * actual answers, folded to literals, so an adapter's
+ * `if (serverRoutes) use(server)` drops its import when no route needs it.
+ */
+/** `true` when some page's component is a server function (`server: true`). */
+export const serverRoutes = true;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { analyzeModule, getExportName, getLocalExportName } from "./analyze.ts";
-export type { StaticExportEntry } from "./analyze.ts";
+export { analyzeModule, analyzeRouteModule, getExportName, getLocalExportName } from "./analyze.ts";
+export type { RouteModuleAnalysis, StaticExportEntry } from "./analyze.ts";
 export type { ModuleRef, RouteManifestEntry } from "./manifest.ts";
 export { BaseFileSystemRouter, cleanPath, glob, normalizePath, type FileSystemRouterConfig } from "./router.ts";
 export { HTTP_METHODS, PageFileSystemRouter, routePathFromFile, type PageFileSystemRouterConfig } from "./convention.ts";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { analyzeModule, getExportName, getLocalExportName } from "./analyze.js";
+export { analyzeModule, analyzeRouteModule, getExportName, getLocalExportName } from "./analyze.js";
 export { BaseFileSystemRouter, cleanPath, glob, normalizePath } from "./router.js";
 export { HTTP_METHODS, PageFileSystemRouter, routePathFromFile } from "./convention.js";
 export { FlatFileSystemRouter, flatRoutePathFromFile } from "./flat.js";

package/dist/manifest.d.ts

@@ -27,6 +27,12 @@ export interface ModuleRef {
     src: string;
     /** The named exports (or `"default"`) this ref selects from the module. */
     pick: string[];
+    /**
+     * Deliver eagerly even under code splitting. Set by a convention when the
+     * module has no client code worth a chunk — a server-function page, whose
+     * client side is a stub — so the ref is materialized `{ src, require }`.
+     */
+    eager?: boolean;
 }
 export interface RouteManifestEntry {
     /**
@@ -38,6 +44,13 @@ export interface RouteManifestEntry {
     path: string;
     /** `true` when the module renders a page (has a default export). */
     page?: boolean;
+    /**
+     * `true` when the page component is a server function — its default export
+     * begins with a `"use server"` directive. The convention delivers such a
+     * `$component` eagerly; what a server-rendered page means is the emission
+     * adapter's business.
+     */
+    server?: boolean;
     /** Lazy ref to the page component module. */
     $component?: ModuleRef;
     /** Eager ref to the route config (`route` export), when present. */

package/dist/router.d.ts

@@ -38,14 +38,21 @@ export declare function cleanPath(src: string, config: FileSystemRouterConfig):
  */
 export declare class BaseFileSystemRouter extends EventTarget {
     routes: RouteManifestEntry[];
+    /** Source file that first produced each route path, so incremental changes keep scan order. */
+    private sources;
     config: FileSystemRouterConfig;
+    /**
+     * Route path each source file produced. A removed file can no longer be
+     * passed to `toRoute`, and `toPath` may give another file's route.
+     */
+    private routePaths;
     constructor(config: FileSystemRouterConfig);
     glob(): string;
     buildRoutes(): Promise<RouteManifestEntry[]>;
     isRoute(src: string): boolean;
     toPath(src: string): string | undefined;
     toRoute(src: string): RouteManifestEntry | undefined;
-    _addRoute(route: RouteManifestEntry): boolean;
+    _addRoute(route: RouteManifestEntry, src?: string): boolean;
     addRoute(src: string): Promise<void>;
     reload(route: string, type: "update" | "remove" | "add"): void;
     updateRoute(src_: string): Promise<void>;

package/dist/router.js

@@ -20,7 +20,14 @@ export function cleanPath(src, config) {
  */
 export class BaseFileSystemRouter extends EventTarget {
     routes;
+    /** Source file that first produced each route path, so incremental changes keep scan order. */
+    sources = new Map();
     config;
+    /**
+     * Route path each source file produced. A removed file can no longer be
+     * passed to `toRoute`, and `toPath` may give another file's route.
+     */
+    routePaths = new Map();
     constructor(config) {
         super();
         this.routes = [];
@@ -36,7 +43,7 @@ export class BaseFileSystemRouter extends EventTarget {
         return posix.join(fg.convertPathToPattern(this.config.dir), "**/*") + suffix;
     }
     async buildRoutes() {
-        for (const src of glob(this.glob())) {
+        for (const src of glob(this.glob()).sort()) {
             await this.addRoute(src);
         }
         return this.routes;
@@ -54,12 +61,28 @@ export class BaseFileSystemRouter extends EventTarget {
             return this.config.toRoute(src, this);
         throw new Error("Not implemented");
     }
-    _addRoute(route) {
+    _addRoute(route, src) {
         const idx = this.routes.findIndex(r => r.path === route.path);
-        if (idx >= 0)
-            this.routes.splice(idx, 1);
-        this.routes.push(route);
-        return idx >= 0;
+        if (idx >= 0) {
+            // Replace in place: an edited file keeps its position. The source that
+            // first produced the path still decides it, as in a full scan.
+            this.routes[idx] = route;
+            return true;
+        }
+        if (src !== undefined)
+            this.sources.set(route.path, src);
+        // A new file goes where a full scan would put it.
+        const at = src === undefined
+            ? -1
+            : this.routes.findIndex(r => {
+                const other = this.sources.get(r.path);
+                return other !== undefined && other > src;
+            });
+        if (at === -1)
+            this.routes.push(route);
+        else
+            this.routes.splice(at, 0, route);
+        return false;
     }
     async addRoute(src) {
         src = normalizePath(src);
@@ -67,7 +90,10 @@ export class BaseFileSystemRouter extends EventTarget {
             try {
                 const route = this.toRoute(src);
                 if (route) {
-                    this._addRoute(route);
+                    if (this.routePaths.get(src) !== route.path)
+                        this.removeRoute(src);
+                    this._addRoute(route, src);
+                    this.routePaths.set(src, route.path);
                     this.reload(route.path, "add");
                 }
             }
@@ -90,7 +116,10 @@ export class BaseFileSystemRouter extends EventTarget {
             try {
                 const route = this.toRoute(src);
                 if (route) {
-                    const updated = this._addRoute(route);
+                    if (this.routePaths.get(src) !== route.path)
+                        this.removeRoute(src_);
+                    const updated = this._addRoute(route, src);
+                    this.routePaths.set(src, route.path);
                     this.reload(route.path, updated ? "update" : "add");
                 }
                 else {
@@ -104,17 +133,16 @@ export class BaseFileSystemRouter extends EventTarget {
     }
     removeRoute(src) {
         src = normalizePath(src);
-        if (this.isRoute(src)) {
-            const path = this.toPath(src);
-            if (path === undefined) {
-                return;
-            }
-            const idx = this.routes.findIndex(r => r.path === path);
-            if (idx === -1)
-                return;
-            this.routes.splice(idx, 1);
-            this.reload(path, "remove");
-        }
+        const path = this.routePaths.get(src);
+        if (path === undefined)
+            return;
+        this.routePaths.delete(src);
+        const idx = this.routes.findIndex(r => r.path === path);
+        if (idx === -1)
+            return;
+        this.routes.splice(idx, 1);
+        this.sources.delete(path);
+        this.reload(path, "remove");
     }
     on(type, cb) {
         this.addEventListener(type, cb);

package/dist/tree.js

@@ -21,7 +21,7 @@ export function buildRouteTree(entries) {
         processRoute(parentRoute.children || (parentRoute.children = []), route, id.slice(parentRoute.id.length));
     }
     return [...entries]
-        .sort((a, b) => a.path.length - b.path.length)
+        .sort((a, b) => (a.path.length - b.path.length) || a.path.localeCompare(b.path))
         .reduce((routes, route) => {
         processRoute(routes, route, route.path);
         return routes;

package/dist/vite/constants.d.ts

@@ -6,3 +6,12 @@
  */
 export declare const moduleId = "virtual:file-routes";
 export declare const DEFAULT_EXTENSIONS: string[];
+/**
+ * The module adapters import scan facts from — `filesystem-routing/flags`.
+ * The package ships it as a real file whose facts are all `true` (the safe
+ * answer wherever no plugin hook is in the loop: dev prebundling, a custom
+ * manifest, another bundler); the Vite plugin serves the scan's answer in
+ * builds so gated code folds away.
+ */
+export declare const flagsId = "filesystem-routing/flags";
+export declare const resolvedFlagsId: string;

package/dist/vite/constants.js

@@ -6,3 +6,12 @@
  */
 export const moduleId = "virtual:file-routes";
 export const DEFAULT_EXTENSIONS = ["js", "jsx", "ts", "tsx", "tsrx"];
+/**
+ * The module adapters import scan facts from — `filesystem-routing/flags`.
+ * The package ships it as a real file whose facts are all `true` (the safe
+ * answer wherever no plugin hook is in the loop: dev prebundling, a custom
+ * manifest, another bundler); the Vite plugin serves the scan's answer in
+ * builds so gated code folds away.
+ */
+export const flagsId = "filesystem-routing/flags";
+export const resolvedFlagsId = "\0" + flagsId;

package/dist/vite/index.d.ts

@@ -5,7 +5,7 @@ import { DEFAULT_EXTENSIONS, moduleId } from "./constants.ts";
 export { DEFAULT_EXTENSIONS, moduleId };
 export { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.ts";
 export { fileSystemWatcher } from "./fs-watcher.ts";
-export interface FileRoutesOptions extends Pick<PageFileSystemRouterConfig, "components" | "httpMethods" | "toPath" | "toRoute"> {
+export interface FileRoutesOptions extends Pick<PageFileSystemRouterConfig, "components" | "httpMethods" | "serverComponents" | "toPath" | "toRoute"> {
     /** Route directory, relative to the Vite root. Defaults to `src/routes`. */
     dir?: string;
     /** File extensions that participate in routing. Defaults to js/jsx/ts/tsx. */

package/dist/vite/index.js

@@ -3,7 +3,7 @@ import { dirname, relative, resolve } from "node:path";
 import { PageFileSystemRouter } from "../convention.js";
 import { normalizePath } from "../router.js";
 import { buildRouteTree } from "../tree.js";
-import { DEFAULT_EXTENSIONS, moduleId } from "./constants.js";
+import { DEFAULT_EXTENSIONS, flagsId, moduleId, resolvedFlagsId } from "./constants.js";
 import { fileSystemWatcher } from "./fs-watcher.js";
 import { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.js";
 import { serializeTypes } from "./types.js";
@@ -21,6 +21,15 @@ const HANDLER_REF = /^\$[A-Z]+$/;
  * own default: the `client` environment is the one client consumer.
  */
 const isServerConsumer = (name, consumer) => (consumer ?? (name === "client" ? "client" : "server")) === "server";
+/**
+ * The id a route module ref is loaded from: its source plus its picks. On the
+ * server a server page's module is loaded whole, because the server-function
+ * handler imports it whole too, and a second (picked) instance would register
+ * the page's server function twice.
+ */
+const toModuleId = (route, ref, serverConsumer) => serverConsumer && route.server === true && ref.src === route.$component?.src
+    ? ref.src
+    : toPickId(ref.src, ref.pick);
 /**
  * The client's view of a shared server manifest: handler refs removed. A
  * client bundle can never invoke a request handler, but serializing its ref
@@ -106,8 +115,6 @@ export function fileRoutes(options = {}) {
         mkdirSync(dirname(file), { recursive: true });
         writeFileSync(file, contents);
     }
-    /** The id a route module ref is loaded from: its source plus its picks. */
-    const toModuleId = (ref) => toPickId(ref.src, ref.pick);
     return [
         {
             name: "filesystem-routing",
@@ -138,6 +145,7 @@ export function fileRoutes(options = {}) {
                         extensions: options.extensions ?? DEFAULT_EXTENSIONS,
                         components: options.components,
                         httpMethods: options.httpMethods,
+                        serverComponents: options.serverComponents,
                         toPath: options.toPath,
                         toRoute: options.toRoute
                     });
@@ -160,7 +168,8 @@ export function fileRoutes(options = {}) {
                 // A client environment on the shared router never serializes
                 // handler refs (see load), so their modules must not become its
                 // build entries either.
-                const routes = options.routers?.[name] || isServerConsumer(name, _config.consumer)
+                const serverConsumer = isServerConsumer(name, _config.consumer);
+                const routes = options.routers?.[name] || serverConsumer
                     ? await router.getRoutes()
                     : stripHandlerRefs(await router.getRoutes());
                 // Every code-split route module is an entry of its own, so the
@@ -169,8 +178,8 @@ export function fileRoutes(options = {}) {
                 const input = [];
                 for (const route of routes) {
                     for (const [key, ref] of Object.entries(route)) {
-                        if (ref && key.startsWith("$") && !key.startsWith("$$")) {
-                            input.push(toModuleId(ref));
+                        if (ref && key.startsWith("$") && !key.startsWith("$$") && !ref.eager) {
+                            input.push(toModuleId(route, ref, serverConsumer));
                         }
                     }
                 }
@@ -181,8 +190,20 @@ export function fileRoutes(options = {}) {
             resolveId(source) {
                 if (source === virtualId)
                     return virtualId;
+                if (source === flagsId)
+                    return resolvedFlagsId;
             },
             async load(loadedId) {
+                if (loadedId === resolvedFlagsId) {
+                    // Facts about the scan, folded to literals so an adapter's static
+                    // imports gated on them tree-shake out of a build that does not
+                    // need them. In serve, always `true`: dev has no size to protect
+                    // and the first server page must work without a restart.
+                    const router = getRouter(this.environment.name);
+                    const routes = (router && (await router.getRoutes())) ?? [];
+                    const serverRoutes = this.environment.mode !== "build" || routes.some(route => route.server === true);
+                    return `export const serverRoutes = ${serverRoutes};`;
+                }
                 if (loadedId !== virtualId)
                     return;
                 const root = this.environment.config.root;
@@ -191,19 +212,19 @@ export function fileRoutes(options = {}) {
                 const environmentName = this.environment.name;
                 const router = getRouter(environmentName);
                 let routes = (router ? await router.getRoutes() : []) ?? [];
+                const serverConsumer = isServerConsumer(environmentName, this.environment.config.consumer);
                 // The shared router serves every environment, so the split is this
                 // adapter's job: client consumers get the manifest without handler
                 // refs. An explicit per-environment router already IS the split —
                 // serve whatever it emits.
-                if (!options.routers?.[environmentName] &&
-                    !isServerConsumer(environmentName, this.environment.config.consumer)) {
+                if (!options.routers?.[environmentName] && !serverConsumer) {
                     routes = stripHandlerRefs(routes);
                 }
                 const serializeEntry = (entry) => JSON.stringify(entry, (key, value) => {
                     if (value === undefined)
                         return undefined;
                     if (key.startsWith("$$")) {
-                        const buildId = toModuleId(value);
+                        const buildId = toModuleId(entry, value, serverConsumer);
                         const refs = {};
                         for (const pick of value.pick) {
                             refs[pick] = js.addNamedImport(pick, buildId);
@@ -215,19 +236,20 @@ export function fileRoutes(options = {}) {
                         };
                     }
                     else if (key.startsWith("$")) {
-                        const buildId = toModuleId(value);
-                        // With code splitting off the ref is delivered eagerly: a
-                        // namespace import (named imports would fail on the synthetic
-                        // `$css` pick) behind the `require()` shape eager refs carry,
-                        // plus the `src` lazy refs already expose.
-                        if (!codeSplitting) {
+                        const buildId = toModuleId(entry, value, serverConsumer);
+                        // With code splitting off — or a ref the convention marked
+                        // `eager` — the ref is delivered eagerly: a namespace import
+                        // (named imports would fail on the synthetic `$css` pick)
+                        // behind the `require()` shape eager refs carry, plus the
+                        // `src` lazy refs already expose.
+                        if (!codeSplitting || value.eager) {
                             return {
-                                src: relative(root, buildId),
+                                src: normalizePath(relative(root, buildId)),
                                 require: `_$() => (${js.addNamespaceImport(buildId)})$_`
                             };
                         }
                         return {
-                            src: relative(root, buildId),
+                            src: normalizePath(relative(root, buildId)),
                             build: isBuild ? `_$() => import('${buildId}')$_` : undefined,
                             import: `_$() => import('${buildId}')$_`
                         };

package/dist/vite/types.js

@@ -32,6 +32,8 @@ const REF_TYPES = `  /** A code-split ref: the delivery adapter emits it as a dy
   export interface FileRouteEntry {
     path: string;
     page?: boolean;
+    /** The page component is a server function; its \`$component\` is delivered eagerly. */
+    server?: boolean;
     $component?: FileRouteLazyRef<any> | FileRouteEagerRef<any>;
     $$route?: FileRouteEagerRef<any>;
     [key: string]: unknown;
@@ -45,19 +47,22 @@ const REF_TYPES = `  /** A code-split ref: the delivery adapter emits it as a dy
 /** Extensions TypeScript can resolve through a `typeof import(...)`. */
 const TYPED_MODULE = /\.([mc]?[jt]sx?)$/;
 /**
- * Types a ref by the module it points at, so a page's `default` really is the
- * component and a `route` export really is the config the module declares —
- * which is what saves an emission adapter from casting either one. Modules
- * TypeScript cannot resolve (`.md`, `.mdx`) fall back to the generic ref.
+ * Types a ref by its picked exports, keeping the module's `default` and
+ * `route` types so an emission adapter can read either without a cast.
+ * Modules TypeScript cannot resolve (`.md`, `.mdx`) fall back to the generic ref.
  */
 function refType(ref, kind, from) {
     const name = kind === "eager" ? "FileRouteEagerRef" : "FileRouteLazyRef";
     if (!TYPED_MODULE.test(ref.src))
         return name;
+    const picks = ref.pick.filter(pick => pick !== "$css").map(pick => JSON.stringify(pick));
+    if (!picks.length)
+        return name;
     let specifier = normalizePath(relative(from, ref.src)).replace(TYPED_MODULE, "");
     if (!specifier.startsWith("."))
         specifier = `./${specifier}`;
-    return `${name}<typeof import(${JSON.stringify(specifier)})>`;
+    const moduleType = `typeof import(${JSON.stringify(specifier)})`;
+    return `${name}<Pick<${moduleType}, Extract<${picks.join(" | ")}, keyof ${moduleType}>>>`;
 }
 const isLazyRefKey = (key) => key.startsWith("$") && !key.startsWith("$$");
 const isEagerRefKey = (key) => key.startsWith("$$");
@@ -72,14 +77,18 @@ function entryType(entry, indent, nested, from, codeSplitting) {
     if (nested)
         fields.push(`id: ${JSON.stringify(entry.id)}`);
     fields.push(`page: ${entry.page ? "true" : "false"}`);
+    if (entry.server)
+        fields.push(`server: true`);
     // A convention records refs it did not emit as present-but-undefined keys,
     // so go by the value, not the key.
     const refKeys = Object.keys(entry).filter(key => key.startsWith("$") && entry[key] !== undefined);
     for (const key of refKeys) {
-        // With code splitting off, the delivery adapter materializes lazy refs
-        // eagerly, so the declaration describes them as delivered.
-        const kind = isEagerRefKey(key) || !codeSplitting ? "eager" : "lazy";
-        fields.push(`${key}: ${refType(entry[key], kind, from)}`);
+        // With code splitting off, or a ref the convention marked `eager`, the
+        // delivery adapter materializes lazy refs eagerly, so the declaration
+        // describes them as delivered.
+        const ref = entry[key];
+        const kind = isEagerRefKey(key) || !codeSplitting || ref.eager ? "eager" : "lazy";
+        fields.push(`${key}: ${refType(ref, kind, from)}`);
     }
     // Reading an absent ref is how adapters branch, so keep the key present.
     if (!refKeys.some(isLazyRefKey))

package/package.json

@@ -2,7 +2,7 @@
   "name": "filesystem-routing",
   "description": "Router-neutral file-system routing: scans a route directory into a neutral route manifest with pluggable conventions and delivery adapters",
   "license": "MIT",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "author": "Ryan Carniato",
   "homepage": "https://github.com/solidjs/filesystem-routing#readme",
   "repository": {
@@ -44,6 +44,10 @@
       "types": "./dist/api.d.ts",
       "default": "./dist/api.js"
     },
+    "./flags": {
+      "types": "./dist/flags.d.ts",
+      "default": "./dist/flags.js"
+    },
     "./types": {
       "types": "./types.d.ts"
     }