filesystem-routing 0.3.1 → 0.4.0

package/README.md

@@ -190,6 +190,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 +354,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/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.js

@@ -36,7 +36,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;

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";
@@ -138,6 +138,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
                     });
@@ -169,7 +170,7 @@ 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("$$")) {
+                        if (ref && key.startsWith("$") && !key.startsWith("$$") && !ref.eager) {
                             input.push(toModuleId(ref));
                         }
                     }
@@ -181,8 +182,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;
@@ -216,18 +229,19 @@ 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) {
+                        // 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;
@@ -72,14 +74,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.0",
   "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"
     }