@solidjs/start 2.0.0-beta.9 → 2.0.0-rc.10

package/dist/config/fs-routes/tree-shake.js

@@ -1,7 +1,52 @@
 // All credit for this work goes to the amazing Next.js team.
 // https://github.com/vercel/next.js/blob/canary/packages/next/build/babel/plugins/next-ssg-transform.ts
 // This is adapted to work with routeData functions. It can be run in two modes, one which preserves the routeData and the Component in the same file, and one which creates a
-import { basename } from "pathe";
+import { basename, extname } from "pathe";
+const PICKABLE_EXTENSIONS = ["js", "jsx", "ts", "tsx"];
+/**
+ * Builds the module id used to import a subset of a route file's exports.
+ *
+ * The `pick` list has to live in the query so that the same file can be
+ * instantiated once per export subset (the client picks `default`/`$css`,
+ * the server picks its HTTP handlers). That query would otherwise leave the
+ * id ending in `?pick=GET`, which silently excludes route files from any
+ * plugin whose filter is anchored on the file extension -- a very common
+ * default, e.g. unplugin-macros' `/\.[cm]?[jt]sx?$/`.
+ *
+ * The trailing `lang.<ext>` marker is the same convention Vue SFCs use
+ * (`?vue&type=script&lang.ts`) and puts a real extension back at the end of
+ * the id, so those filters match again.
+ *
+ * @see https://github.com/solidjs/solid-start/issues/1918
+ */
+export function toPickId(src, pick) {
+    const query = pick.map(p => `pick=${p}`).join("&");
+    const ext = extname(src).slice(1);
+    return PICKABLE_EXTENSIONS.includes(ext) ? `${src}?${query}&lang.${ext}` : `${src}?${query}`;
+}
+/**
+ * Matches the tail that {@link toPickId} appends, as it appears in a chunk
+ * name. Rolldown derives a chunk name from the module id by taking the
+ * basename minus its extension, so `index.tsx?pick=default&pick=$css&lang.tsx`
+ * arrives here as `index.tsx?pick=default&pick=$css&lang`.
+ */
+const PICK_CHUNK_NAME_RE = /\.[cm]?[jt]sx?\?pick=[^?]*&lang$/;
+const INVALID_CHAR_RE = /[\u0000-\u001F"#$&*+,:;<=>?[\]^`{|}\u007F]/g;
+const DRIVE_LETTER_RE = /^[a-z]:/i;
+/**
+ * Rolldown's default chunk name sanitizer, plus a pass that drops the
+ * `?pick=...&lang` tail so route chunks keep the short, stable filenames they
+ * had before the `lang` marker was introduced (`index-<hash>.js`, not
+ * `index.tsx_pick_default_pick__css_lang-<hash>.js`). Client chunk filenames
+ * are public URLs, so this is not purely cosmetic.
+ *
+ * @see https://github.com/rollup/rollup/blob/master/src/utils/sanitizeFileName.ts
+ */
+export function sanitizeChunkFileName(name) {
+    const stripped = name.replace(PICK_CHUNK_NAME_RE, "");
+    const driveLetter = DRIVE_LETTER_RE.exec(stripped)?.[0] ?? "";
+    return driveLetter + stripped.slice(driveLetter.length).replace(INVALID_CHAR_RE, "_");
+}
 function treeShakeTransform({ types: t }) {
     function getIdentifier(path) {
         const parentPath = path.parentPath;
@@ -20,13 +65,28 @@ function treeShakeTransform({ types: t }) {
         }
         return path.node.id && path.node.id.type === "Identifier" ? path.get("id") : null;
     }
-    function isIdentifierReferenced(ident) {
+    function isTypeOnlyReference(path) {
+        return path.getAncestry().some(parent => {
+            if (parent.isTSType())
+                return true;
+            if (parent.isExportNamedDeclaration())
+                return parent.node.exportKind === "type";
+            if (parent.isExportSpecifier())
+                return parent.node.exportKind === "type";
+            return false;
+        });
+    }
+    function runtimeReferences(binding) {
+        return binding.referencePaths.filter(ref => !isTypeOnlyReference(ref));
+    }
+    function isIdentifierReferenced(ident, includeTypes = false) {
         const b = ident.scope.getBinding(ident.node.name);
-        if (b?.referenced) {
+        if (b) {
+            const references = b.constantViolations.concat(includeTypes ? b.referencePaths : runtimeReferences(b));
+            if (!references.length)
+                return false;
             if (b.path.type === "FunctionDeclaration") {
-                return !b.constantViolations
-                    .concat(b.referencePaths)
-                    .every(ref => ref.findParent(p => p === b.path));
+                return !references.every(ref => ref.findParent(p => p === b.path));
             }
             return true;
         }
@@ -34,13 +94,13 @@ function treeShakeTransform({ types: t }) {
     }
     function markFunction(path, state) {
         const ident = getIdentifier(path);
-        if (ident && ident.node && isIdentifierReferenced(ident)) {
+        if (ident && ident.node && isIdentifierReferenced(ident, true)) {
             state.refs.add(ident);
         }
     }
     function markImport(path, state) {
         const local = path.get("local");
-        if (isIdentifierReferenced(local)) {
+        if (isIdentifierReferenced(local, true)) {
             state.refs.add(local);
         }
     }
@@ -49,12 +109,13 @@ function treeShakeTransform({ types: t }) {
             Program: {
                 enter(path, state) {
                     state.refs = new Set();
+                    state.candidates = new Set();
                     state.done = false;
                     path.traverse({
                         VariableDeclarator(variablePath, variableState) {
                             if (variablePath.node.id.type === "Identifier") {
                                 const local = variablePath.get("id");
-                                if (isIdentifierReferenced(local)) {
+                                if (isIdentifierReferenced(local, true)) {
                                     variableState.refs.add(local);
                                 }
                             }
@@ -69,7 +130,7 @@ function treeShakeTransform({ types: t }) {
                                             : (() => {
                                                 throw new Error("invariant");
                                             })());
-                                    if (isIdentifierReferenced(local)) {
+                                    if (isIdentifierReferenced(local, true)) {
                                         variableState.refs.add(local);
                                     }
                                 });
@@ -88,29 +149,46 @@ function treeShakeTransform({ types: t }) {
                                     else {
                                         return;
                                     }
-                                    if (isIdentifierReferenced(local)) {
+                                    if (isIdentifierReferenced(local, true)) {
                                         variableState.refs.add(local);
                                     }
                                 });
                             }
                         },
                         ExportDefaultDeclaration(exportNamedPath) {
-                            // if opts.keep is true, we don't remove the routeData export
                             if (state.opts.pick && !state.opts.pick.includes("default")) {
-                                exportNamedPath.remove();
+                                const decl = exportNamedPath.node.declaration;
+                                // A named function/class declaration creates a module-scope
+                                // binding that picked exports may reference, so only strip
+                                // the `export default`; the sweep below removes the
+                                // declaration again if nothing references it.
+                                if ((t.isFunctionDeclaration(decl) || t.isClassDeclaration(decl)) && decl.id) {
+                                    const [newPath] = exportNamedPath.replaceWith(decl);
+                                    const id = newPath.get("id");
+                                    state.refs.add(id);
+                                    state.candidates.add(id);
+                                }
+                                else {
+                                    exportNamedPath.remove();
+                                }
                             }
                         },
                         ExportNamedDeclaration(exportNamedPath) {
-                            // if opts.keep is false, we don't remove the routeData export
+                            // No pick list means nothing gets pruned.
                             if (!state.opts.pick) {
                                 return;
                             }
+                            // Only module-level exports are route exports; `export` inside a
+                            // TS namespace/module block is unrelated to the pick list.
+                            if (!exportNamedPath.parentPath.isProgram()) {
+                                return;
+                            }
                             const specifiers = exportNamedPath.get("specifiers");
                             if (specifiers.length) {
                                 specifiers.forEach(s => {
-                                    if (t.isIdentifier(s.node.exported)
-                                        ? s.node.exported.name
-                                        : state.opts.pick.includes(s.node.exported.value)) {
+                                    const exported = s.node.exported;
+                                    const exportedName = t.isIdentifier(exported) ? exported.name : exported.value;
+                                    if (!state.opts.pick.includes(exportedName)) {
                                         s.remove();
                                     }
                                 });
@@ -124,24 +202,51 @@ function treeShakeTransform({ types: t }) {
                                 return;
                             }
                             switch (decl.node.type) {
-                                case "FunctionDeclaration": {
+                                case "FunctionDeclaration":
+                                case "ClassDeclaration": {
                                     const name = decl.node.id?.name;
                                     if (name && state.opts.pick && !state.opts.pick.includes(name)) {
-                                        exportNamedPath.remove();
+                                        // Keep the declaration in module scope since picked
+                                        // exports may reference it; the sweep below removes it
+                                        // again if unreferenced.
+                                        const [newPath] = exportNamedPath.replaceWith(decl.node);
+                                        const id = newPath.get("id");
+                                        state.refs.add(id);
+                                        state.candidates.add(id);
                                     }
                                     break;
                                 }
                                 case "VariableDeclaration": {
-                                    const inner = decl.get("declarations");
-                                    inner.forEach(d => {
-                                        if (d.node.id.type !== "Identifier") {
-                                            return;
-                                        }
-                                        const name = d.node.id.name;
-                                        if (state.opts.pick && !state.opts.pick.includes(name)) {
-                                            d.remove();
-                                        }
+                                    const declNode = decl.node;
+                                    // Destructuring declarators are conservatively treated as
+                                    // picked (matching the previous behavior of leaving them
+                                    // untouched).
+                                    const isPicked = (d) => d.id.type !== "Identifier" || state.opts.pick.includes(d.id.name);
+                                    if (declNode.declarations.every(isPicked)) {
+                                        break;
+                                    }
+                                    // Split into one declaration per declarator (preserving
+                                    // evaluation order) and export only the picked ones.
+                                    // Unpicked bindings are kept since picked exports may
+                                    // reference them; the sweep below removes them again if
+                                    // unreferenced.
+                                    const statements = declNode.declarations.map(d => {
+                                        const single = t.variableDeclaration(declNode.kind, [d]);
+                                        single.declare = declNode.declare;
+                                        return isPicked(d) ? t.exportNamedDeclaration(single, []) : single;
                                     });
+                                    const newPaths = exportNamedPath.replaceWithMultiple(statements);
+                                    for (const p of newPaths) {
+                                        if (!p.isVariableDeclaration())
+                                            continue;
+                                        for (const d of p.get("declarations")) {
+                                            if (d.node.id.type === "Identifier") {
+                                                const id = d.get("id");
+                                                state.refs.add(id);
+                                                state.candidates.add(id);
+                                            }
+                                        }
+                                    }
                                     break;
                                 }
                                 default: {
@@ -152,6 +257,8 @@ function treeShakeTransform({ types: t }) {
                         FunctionDeclaration: markFunction,
                         FunctionExpression: markFunction,
                         ArrowFunctionExpression: markFunction,
+                        ClassDeclaration: markFunction,
+                        ClassExpression: markFunction,
                         ImportSpecifier: markImport,
                         ImportDefaultSpecifier: markImport,
                         ImportNamespaceSpecifier: markImport,
@@ -163,11 +270,95 @@ function treeShakeTransform({ types: t }) {
                             }
                         },
                     }, state);
+                    // References alone cannot distinguish live bindings from dead cycles.
+                    // Build a graph of localized exports and retain only those reachable
+                    // from runtime code outside that graph.
+                    path.scope.crawl();
+                    const tracked = new Map();
+                    const candidateOwners = new Map();
+                    const addOwner = (owners, binding, owner) => {
+                        const paths = owners.get(binding) ?? new Set();
+                        paths.add(owner);
+                        owners.set(binding, paths);
+                    };
+                    for (const identifier of state.refs) {
+                        if (identifier.node?.type !== "Identifier" || !identifier.parentPath)
+                            continue;
+                        const binding = identifier.scope.getBinding(identifier.node.name);
+                        if (binding)
+                            addOwner(tracked, binding, identifier.parentPath);
+                    }
+                    for (const identifier of state.candidates) {
+                        if (!identifier.parentPath)
+                            continue;
+                        const binding = identifier.scope.getBinding(identifier.node.name);
+                        if (!binding)
+                            continue;
+                        addOwner(tracked, binding, identifier.parentPath);
+                        addOwner(candidateOwners, binding, identifier.parentPath);
+                    }
+                    const dependencies = new Map();
+                    const live = new Set();
+                    for (const [binding, owners] of tracked) {
+                        dependencies.set(binding, new Set());
+                        if ([...owners].some(owner => owner.findParent(parent => parent.isExportNamedDeclaration() || parent.isExportDefaultDeclaration()))) {
+                            live.add(binding);
+                        }
+                    }
+                    const ownerBindings = new Map();
+                    for (const [binding, owners] of tracked) {
+                        for (const owner of owners) {
+                            ownerBindings.set(owner, binding);
+                        }
+                    }
+                    const owningBinding = (reference) => {
+                        const owner = reference.find(parent => ownerBindings.has(parent));
+                        return owner && ownerBindings.get(owner);
+                    };
+                    for (const target of tracked.keys()) {
+                        const references = target.constantViolations.concat(runtimeReferences(target));
+                        for (const reference of references) {
+                            const source = owningBinding(reference);
+                            if (source)
+                                dependencies.get(source)?.add(target);
+                            else
+                                live.add(target);
+                        }
+                    }
+                    const pending = [...live];
+                    while (pending.length) {
+                        const source = pending.pop();
+                        for (const dependency of dependencies.get(source) ?? []) {
+                            if (live.has(dependency))
+                                continue;
+                            live.add(dependency);
+                            pending.push(dependency);
+                        }
+                    }
+                    const deadCandidates = new Set([...candidateOwners.keys()].filter(candidate => !live.has(candidate)));
+                    path.traverse({
+                        VariableDeclarator(variablePath) {
+                            if (variablePath.node.id.type !== "Identifier")
+                                return;
+                            const binding = variablePath.scope.getBinding(variablePath.node.id.name);
+                            if (binding && deadCandidates.has(binding))
+                                variablePath.remove();
+                        },
+                    });
+                    for (const [candidate, owners] of candidateOwners) {
+                        if (!deadCandidates.has(candidate))
+                            continue;
+                        for (const owner of owners) {
+                            if (!owner.removed && !owner.isVariableDeclarator())
+                                owner.remove();
+                        }
+                    }
                     const refs = state.refs;
+                    const refNodes = new Set([...refs].map(ref => ref.node));
                     let count = 0;
                     const sweepFunction = (sweepPath) => {
                         const ident = getIdentifier(sweepPath);
-                        if (ident && ident.node && refs.has(ident) && !isIdentifierReferenced(ident)) {
+                        if (ident && ident.node && refNodes.has(ident.node) && !isIdentifierReferenced(ident)) {
                             ++count;
                             if (t.isAssignmentExpression(sweepPath.parentPath) ||
                                 t.isVariableDeclarator(sweepPath.parentPath)) {
@@ -180,7 +371,7 @@ function treeShakeTransform({ types: t }) {
                     };
                     function sweepImport(sweepPath) {
                         const local = sweepPath.get("local");
-                        if (refs.has(local) && !isIdentifierReferenced(local)) {
+                        if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
                             ++count;
                             sweepPath.remove();
                             if (sweepPath.parent.specifiers.length === 0) {
@@ -195,7 +386,7 @@ function treeShakeTransform({ types: t }) {
                             VariableDeclarator(variablePath) {
                                 if (variablePath.node.id.type === "Identifier") {
                                     const local = variablePath.get("id");
-                                    if (refs.has(local) && !isIdentifierReferenced(local)) {
+                                    if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
                                         ++count;
                                         variablePath.remove();
                                     }
@@ -212,7 +403,7 @@ function treeShakeTransform({ types: t }) {
                                                 : (() => {
                                                     throw new Error("invariant");
                                                 })());
-                                        if (refs.has(local) && !isIdentifierReferenced(local)) {
+                                        if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
                                             ++count;
                                             p.remove();
                                         }
@@ -236,7 +427,7 @@ function treeShakeTransform({ types: t }) {
                                         else {
                                             return;
                                         }
-                                        if (refs.has(local) && !isIdentifierReferenced(local)) {
+                                        if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
                                             ++count;
                                             e.remove();
                                         }
@@ -249,6 +440,8 @@ function treeShakeTransform({ types: t }) {
                             FunctionDeclaration: sweepFunction,
                             FunctionExpression: sweepFunction,
                             ArrowFunctionExpression: sweepFunction,
+                            ClassDeclaration: sweepFunction,
+                            ClassExpression: sweepFunction,
                             ImportSpecifier: sweepImport,
                             ImportDefaultSpecifier: sweepImport,
                             ImportNamespaceSpecifier: sweepImport,

package/dist/config/index.d.ts

@@ -1,25 +1,174 @@
-import type { PluginOption } from "vite";
+import type { PluginOption, FilterPattern } from "vite";
 import { type Options as SolidOptions } from "vite-plugin-solid";
 import { type ServerFunctionsOptions } from "../directives/index.ts";
 import { type EnvPluginOptions } from "./env.ts";
+/**
+ * Configuration options for SolidStart. (previously in `app.config.ts`)
+ *
+ * @see https://docs.solidjs.com/solid-start/v2/migrating-from-v1#move-framework-configuration-into-viteconfigts
+ */
 export interface SolidStartOptions {
+    /**
+     * Path to the root of the application (where `app.tsx` / `app.jsx` lives).
+     *
+     * @default "./src"
+     */
+    appRoot?: string;
+    /**
+     * Options related to the css crawling logic
+     */
+    css?: {
+        /**
+         * Filter files included during css crawling in development.
+         */
+        filter?: {
+            include?: FilterPattern;
+            exclude?: FilterPattern;
+        };
+    };
+    /**
+     * Options forwarded to `vite-plugin-solid`.
+     *
+     * @see https://github.com/solidjs/vite-plugin-solid#api
+     */
     solid?: Partial<SolidOptions>;
+    /**
+     * Enable or disable server-side rendering.
+     *
+     * - `true` — SSR (default)
+     * - `false` — client-side rendering only (SPA mode)
+     *
+     * @default true
+     */
     ssr?: boolean;
+    /**
+     * Show the SolidStart development overlay (error overlay, etc.) in development.
+     *
+     * @default true
+     */
+    devOverlay?: boolean;
+    /**
+     * Experimental features.
+     */
+    experimental?: {
+        /**
+         * Enable islands architecture mode.
+         *
+         * Currently fixed to `false` (not yet fully supported).
+         *
+         * @default false
+         */
+        islands?: false;
+    };
+    /**
+     * Directory containing file-system routes, relative to {@link appRoot}.
+     *
+     * @default "./routes"
+     */
     routeDir?: string;
+    /**
+     * File extensions that should be treated as routes.
+     *
+     * @default ["js", "jsx", "ts", "tsx"]
+     */
     extensions?: string[];
+    /**
+     * Path to an optional middleware module.
+     *
+     * The module should export a middleware created with `createMiddleware`
+     * from `@solidjs/start/middleware`.
+     *
+     * @example "src/middleware/index.ts"
+     */
     middleware?: string;
+    /**
+     * Serialization settings for server-function / action payloads
+     * that cross the server-client boundary.
+     */
     serialization?: {
         /**
          * The serialization mode to use for server functions/actions.
-         * The "js" mode uses a custom binary format that is more efficient than JSON, but requires a custom deserializer (with `eval()`) on the client.
-         * A strong CSP should block `eval()` executions, which would prevent the "js" mode from working.
-         * The "json" mode uses JSON for serialization, which is less efficient but can be deserialized with `JSON.parse` on the client.
+         *
+         * - `"js"` — Uses a custom binary format (Seroval) that is more efficient
+         *   than JSON, but requires a custom deserializer (with `eval()`) on the client.
+         *   A strong CSP that blocks `eval()` will prevent this mode from working.
+         * - `"json"` — Uses JSON for serialization. Less efficient / larger payloads,
+         *   but can be deserialized with `JSON.parse` on the client and is CSP-friendly.
          *
          * @default "json"
          */
         mode?: "js" | "json";
+        /**
+         * Path to a module whose default export is an array of custom Seroval
+         * plugins, used to serialize values Seroval doesn't understand natively
+         * (ORM id types, decimals, `Temporal`, and other custom classes).
+         *
+         * Build plugins with `createPlugin` from `seroval`. The module is bundled
+         * into both the client and the server so that both ends of a server
+         * function agree on the format, so it must not import server-only code.
+         *
+         * SolidStart's built-in plugins take precedence: Seroval uses the first
+         * plugin whose `test()` passes, and these are appended after the built-ins.
+         *
+         * A plugin's `deserialize` rebuilds the value under {@link mode} `"json"`.
+         * `serialize` is only used by `mode: "js"`, where the payload is evaluated
+         * on the client and may therefore reference globals only, not the plugin
+         * module's own imports.
+         *
+         * Only applies to server-function and action payloads. The SSR hydration
+         * payload is serialized by `solid-js/web` and is unaffected.
+         *
+         * @example "src/seroval-plugins.ts"
+         */
+        plugins?: string;
     };
+    /**
+     * Configures plugin behavior per build environment
+     */
     env?: EnvPluginOptions;
-    serverFunctions?: Pick<ServerFunctionsOptions, "filter">;
+    /**
+     * Options for server functions: which files the `"use server"` transform
+     * processes (inclusion / exclusion filters), and what happens when a server
+     * function throws.
+     */
+    serverFunctions?: Pick<ServerFunctionsOptions, "filter"> & {
+        /**
+         * Path to a module whose default export handles whatever a server function
+         * throws, before it reaches the client. Use it to report failures to a
+         * monitoring service, or to replace an error carrying internal detail with
+         * one that is safe to send.
+         *
+         * Only server function calls made over the network run through it. A
+         * server function called during rendering runs in process and throws
+         * straight to its caller, and errors from API routes never reach it
+         * either.
+         *
+         * The handler may be asynchronous. SolidStart awaits its return value
+         * before serializing the response, allowing a monitoring service to flush
+         * first. The resolved value decides what the client sees:
+         *
+         * - `undefined` (or `null`) sends what was thrown, unchanged.
+         * - A `Response` is passed through unchanged, which keeps a thrown
+         *   `redirect()` working.
+         * - Any other value is sent in place of what was thrown, and the client
+         *   call rejects with it.
+         * - If the handler throws or rejects, what the server function threw is
+         *   sent unchanged.
+         *
+         * Control flow reaches the export the same way errors do, so a handler
+         * that replaces everything it sees turns redirects into errors.
+         *
+         * Whatever is sent gets serialized to the client along with its own
+         * properties, so an error meant to be safe to expose must not carry
+         * internal detail.
+         *
+         * Type the export as `ServerFunctionErrorHandler` from
+         * `@solidjs/start/server`. The module is bundled into the server only, so
+         * it may import server-only code such as a monitoring SDK.
+         *
+         * @example "src/server-fn-error.ts"
+         */
+        onError?: string;
+    };
 }
 export declare function solidStart(options?: SolidStartOptions): Array<PluginOption>;