@kasperrt/smolter 0.2.0 → 0.3.1

package/.generated/server/handler.ts

@@ -0,0 +1,69 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { send, webRequest } from "./http.ts";
+
+/** Server module produced by an application's SSR entrypoint. */
+export interface ServerBuild {
+  default: (request: Request, entry: string) => Response | Promise<Response>;
+  handleDataRequest: (request: Request) => Response | Promise<Response>;
+}
+
+export interface RequestHandlerOptions {
+  build: ServerBuild;
+  /** Browser entry URL resolved from Vite's production manifest. */
+  entry: string;
+}
+
+export interface ServerIncomingMessage extends IncomingMessage {
+  /** Express supplies this using the application's trust proxy policy. */
+  protocol?: string;
+  originalUrl?: string;
+}
+
+export type NextHandler = (error?: unknown) => void;
+
+/** Node/Express middleware; mount after metrics, tracing and static assets. */
+export function createRequestHandler({
+  build,
+  entry,
+}: RequestHandlerOptions): (
+  incoming: ServerIncomingMessage,
+  outgoing: ServerResponse,
+  next: NextHandler,
+) => Promise<void> {
+  return (
+    incoming: ServerIncomingMessage,
+    outgoing: ServerResponse,
+    next: NextHandler,
+  ): Promise<void> => {
+    const handle = async () => {
+      const url = new URL(
+        incoming.originalUrl ?? incoming.url ?? "/",
+        "http://local",
+      );
+      const dataRequest = url.pathname === "/_smolter";
+      const target = dataRequest ? url.searchParams.get("url") : undefined;
+
+      if (
+        dataRequest &&
+        (!target?.startsWith("/") ||
+          new URL(target, "http://local").origin !== "http://local")
+      ) {
+        await send(
+          new Response("Invalid route URL", { status: 400 }),
+          outgoing,
+        );
+
+        return;
+      }
+
+      const request = await webRequest(incoming, outgoing, target ?? undefined);
+      const response = dataRequest
+        ? await build.handleDataRequest(request)
+        : await build.default(request, entry);
+
+      await send(response, outgoing);
+    };
+
+    return handle().catch(next);
+  };
+}

package/.generated/server/http.ts

@@ -0,0 +1,55 @@
+import type { ServerResponse } from "node:http";
+import type { ServerIncomingMessage } from "./handler.ts";
+
+export async function webRequest(
+  incoming: ServerIncomingMessage,
+  outgoing: ServerResponse,
+  target?: string,
+): Promise<Request> {
+  const origin = `${incoming.protocol ?? "http"}://${incoming.headers.host}`;
+  const headers = new Headers();
+
+  for (const [name, value] of Object.entries(incoming.headers)) {
+    if (value)
+      headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+  }
+
+  const controller = new AbortController();
+  outgoing.once("close", () => controller.abort());
+  const chunks: Uint8Array[] = [];
+
+  for await (const chunk of incoming) chunks.push(chunk);
+
+  return new Request(
+    new URL(target ?? incoming.originalUrl ?? incoming.url ?? "/", origin),
+    {
+      method: incoming.method,
+      headers,
+      signal: controller.signal,
+      ...(incoming.method !== "GET" &&
+        incoming.method !== "HEAD" && {
+          body: new Uint8Array(Buffer.concat(chunks)),
+        }),
+    },
+  );
+}
+
+export async function send(response: Response, outgoing: ServerResponse) {
+  outgoing.statusCode = response.status;
+  response.headers.forEach((value, name) => {
+    if (name !== "set-cookie") outgoing.setHeader(name, value);
+  });
+  const cookies = response.headers.getSetCookie();
+
+  if (cookies.length)
+    outgoing.setHeader(
+      "set-cookie",
+      cookies.map((cookie) =>
+        process.env.NODE_ENV === "production"
+          ? cookie
+          : cookie.replace(/; Secure/gi, ""),
+      ),
+    );
+
+  outgoing.end(new Uint8Array(await response.arrayBuffer()));
+}

package/{src/internal → .generated}/server/index.ts

@@ -4,7 +4,7 @@
  */
 
 import {
-  createRouter,
+  createDataRouter,
   type DataFunction,
   matchRoutes,
   type Route,
@@ -38,7 +38,7 @@ export async function loadRouter(
     loader: wrap(route.loader),
     action: wrap(route.action),
   }));
-  const router = createRouter(serverRoutes, { url });
+  const router = createDataRouter(serverRoutes, { url });
 
   await router.navigate(url);
 
@@ -52,7 +52,7 @@ export async function loadRouter(
         route.path === snapshot.path && route.clientLoader && !route.loader,
     )
   ) {
-    return createRouter(serverRoutes, {
+    return createDataRouter(serverRoutes, {
       url,
       hydrationData: { ...snapshot, loaded: false, state: "loading" },
     });

package/.generated/server/node.ts

@@ -0,0 +1,4 @@
+/** Optional application integration. @module */
+
+export * from "./handler.ts";
+export * from "./http.ts";

package/.generated/server/preact.ts

@@ -0,0 +1,7 @@
+/** Preact server rendering and HTTP data dispatch. @module */
+
+export {
+  dispatchRoute,
+  renderApplication,
+} from "./application.tsx";
+export * from "./index.ts";

package/.generated/vite/application/browser-boundary.ts

@@ -0,0 +1,42 @@
+import { builtinModules } from "node:module";
+import type { Plugin } from "vite";
+
+const builtins = new Set(builtinModules.flatMap((id) => [id, `node:${id}`]));
+
+const forbiddenModules = [
+  /(?:vite-browser-external|__vite-browser-external)/,
+  /\/node_modules\/(?:react|react-dom|react-router|react-router-dom)\//,
+  /\/smolter\/dist\/(?:internal\/)?(?:server|vite|files)\//,
+  /\/smolter\/packages\/(?:server|vite)\/src\//,
+  /\/vite\/dist\/node\//,
+  /\/src\/[^?]*\.server\.[cm]?[jt]sx?(?:\?|$)/,
+];
+
+/** Check emitted modules, after tree shaking, rather than import strings. */
+export function browserBoundary(): Plugin {
+  return {
+    name: "smolter-browser-boundary",
+    apply: "build",
+    applyToEnvironment: (environment) => environment.name === "client",
+    generateBundle(_options, bundle) {
+      for (const output of Object.values(bundle)) {
+        if (output.type !== "chunk") continue;
+
+        for (const id of [...output.imports, ...output.dynamicImports]) {
+          if (!builtins.has(id)) continue;
+
+          this.error(`Node builtin in browser chunk ${output.fileName}: ${id}`);
+        }
+
+        for (const id of Object.keys(output.modules)) {
+          const normalized = id.replaceAll("\\", "/");
+
+          if (!forbiddenModules.some((pattern) => pattern.test(normalized)))
+            continue;
+
+          this.error(`Unexpected browser module in ${output.fileName}: ${id}`);
+        }
+      }
+    },
+  };
+}

package/.generated/vite/application/lazy-files.ts

@@ -0,0 +1,138 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { flatRoutes } from "../../files/index.ts";
+import { type Plugin, transformWithOxc } from "vite";
+
+// Reuse Smolter's file discovery and server-export stripping. Only the browser
+// route manifest changes: matched routes load before their data is committed.
+export function lazyFiles(directory: string): Plugin {
+  let root: string;
+  const modules = new Map<string, string>();
+
+  return {
+    name: "smolter-lazy-routes",
+    enforce: "pre",
+    configResolved(config) {
+      root = resolve(config.root, directory);
+    },
+    generateBundle(_options, bundle) {
+      if (!modules.size) return;
+
+      const routes = [];
+
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== "chunk" || !chunk.facadeModuleId) continue;
+
+        const path = modules.get(chunk.facadeModuleId);
+
+        if (!path) continue;
+
+        const files = new Set<string>();
+
+        function visit(file: string) {
+          if (files.has(file)) return;
+
+          files.add(file);
+
+          const dependency = bundle[file];
+
+          if (dependency?.type !== "chunk") return;
+
+          for (const imported of dependency.imports) visit(imported);
+        }
+
+        visit(chunk.fileName);
+        routes.push({ path, files: [...files] });
+      }
+
+      const paths = [...modules.values()];
+
+      routes.sort(
+        (left, right) => paths.indexOf(left.path) - paths.indexOf(right.path),
+      );
+
+      this.emitFile({
+        type: "asset",
+        fileName: ".vite/route-assets.json",
+        source: JSON.stringify(routes),
+      });
+    },
+    async load(id, options) {
+      if (id !== "\0virtual:smolter/routes" || options?.ssr) return;
+
+      const routes = await flatRoutes(root);
+
+      if (routes instanceof Error) return this.error(routes.message);
+
+      modules.clear();
+
+      const definitions: string[] = [];
+
+      for (const route of routes) {
+        this.addWatchFile(route.file);
+
+        const source = await readFile(route.file, "utf8");
+        const transformed = await transformWithOxc(source, route.file);
+        const ast = this.parse(transformed.code);
+        const fields: Record<string, string | boolean> = { path: route.path };
+
+        for (const statement of ast.body) {
+          if (statement.type === "ExportDefaultDeclaration") {
+            fields.default = true;
+            continue;
+          }
+
+          if (statement.type !== "ExportNamedDeclaration") continue;
+
+          if (statement.declaration?.type === "FunctionDeclaration") {
+            const name = statement.declaration.id?.name;
+
+            if (name) fields[name] = true;
+          }
+
+          for (const specifier of statement.specifiers) {
+            const name =
+              specifier.exported.type === "Identifier"
+                ? specifier.exported.name
+                : specifier.exported.value;
+
+            fields[name] = true;
+          }
+
+          if (statement.declaration?.type !== "VariableDeclaration") continue;
+
+          for (const declaration of statement.declaration.declarations) {
+            if (declaration.id.type === "Identifier")
+              fields[declaration.id.name] = true;
+
+            if (
+              declaration.id.type !== "Identifier" ||
+              declaration.init?.type !== "Literal" ||
+              typeof declaration.init.value !== "string"
+            )
+              continue;
+
+            const name = declaration.id.name;
+
+            if (name === "id") fields.id = declaration.init.value;
+
+            if (name === "routePath") fields.path = declaration.init.value;
+          }
+        }
+
+        const file = `${route.file.replaceAll("\\", "/")}?smolter-client`;
+
+        if (fields.default) modules.set(file, String(fields.path));
+
+        definitions.push(
+          `lazyRoute(${JSON.stringify(fields)}, () => import(${JSON.stringify(file)}))`,
+        );
+      }
+
+      return [
+        'import { lazyRoute } from "@kasperrt/smolter/preact/lazy-route";',
+        `export default [${definitions.join(",\n")}];`,
+      ].join("\n");
+    },
+  };
+}

package/.generated/vite/application/vite.ts

@@ -0,0 +1,144 @@
+import { send, webRequest } from "../../server/http.ts";
+import { routerPlugin } from "../index.ts";
+import type { Plugin, UserConfig } from "vite";
+import { browserBoundary } from "./browser-boundary.ts";
+import { lazyFiles } from "./lazy-files.ts";
+
+export interface ApplicationOptions {
+  directory?: string;
+  ssr?: boolean;
+  splitRoutes?: boolean;
+  resourceRequest?: (url: string) => boolean;
+}
+export const preactConfig: UserConfig = {
+  resolve: {
+    alias: [
+      {
+        find: /^react\/jsx-dev-runtime$/,
+        replacement: "preact/jsx-dev-runtime",
+      },
+      { find: /^react\/jsx-runtime$/, replacement: "preact/jsx-runtime" },
+      { find: /^react-dom\/client$/, replacement: "preact/compat/client" },
+      { find: /^react-dom\/server$/, replacement: "preact-render-to-string" },
+      { find: /^react-dom$/, replacement: "preact/compat" },
+      { find: /^react$/, replacement: "preact/compat" },
+    ],
+    dedupe: ["preact", "@kasperrt/smolter"],
+  },
+  ssr: {
+    noExternal: ["@kasperrt/smolter"],
+  },
+  optimizeDeps: {
+    include: [
+      "preact",
+      "preact/hooks",
+      "preact/compat",
+      "preact/jsx-runtime",
+      "@kasperrt/smolter/preact",
+      "@kasperrt/smolter/preact/lazy-route",
+    ],
+  },
+};
+
+export function applicationPlugins({
+  directory = "src/routes",
+  ssr = true,
+  splitRoutes = true,
+  resourceRequest,
+}: ApplicationOptions = {}): Plugin[] {
+  const application: Plugin = {
+    name: "smolter-application",
+    enforce: "pre",
+    config: () => preactConfig,
+    transformIndexHtml: {
+      order: "post",
+      handler(html, context) {
+        if (!context.server || !ssr) return html;
+
+        // Vite prepends its client ahead of the SSR head. That shifts Preact's
+        // hydration order and detaches loaded stylesheets while moving nodes.
+        // Keep development-only scripts after the application document instead.
+        const client = html.match(
+          /\s*<script\b[^>]*src="[^"]*\/@vite\/client"[^>]*><\/script>\s*/,
+        )?.[0];
+
+        if (!client) return html;
+
+        return html
+          .replace(client, "")
+          .replace("</body>", `${client.trim()}</body>`);
+      },
+    },
+    configureServer(server) {
+      // Own the HTTP adapter so redirects retain authentication cookies.
+      server.middlewares.use((incoming, outgoing, next) => {
+        if (!incoming.url?.startsWith("/_smolter?")) return next();
+
+        const run = async () => {
+          const target = new URL(
+            incoming.url!,
+            "http://local",
+          ).searchParams.get("url");
+
+          if (!target?.startsWith("/") || target.startsWith("//"))
+            return send(
+              new Response("Invalid route URL", { status: 400 }),
+              outgoing,
+            );
+
+          const request = await webRequest(incoming, outgoing, target);
+          const [{ default: routes }, { dispatchRoute }] = await Promise.all([
+            server.ssrLoadModule("virtual:smolter/routes"),
+            server.ssrLoadModule("@kasperrt/smolter/preact/server"),
+          ]);
+          await send(await dispatchRoute(request, routes), outgoing);
+        };
+        void run().catch(next);
+      });
+
+      if (!ssr) return;
+
+      return () => {
+        server.middlewares.use((incoming, outgoing, next) => {
+          if (
+            !incoming.headers.accept?.includes("text/html") &&
+            !resourceRequest?.(incoming.originalUrl ?? incoming.url ?? "")
+          )
+            return next();
+
+          const run = async () => {
+            const request = await webRequest(incoming, outgoing);
+            const entry = await server.ssrLoadModule("/src/entry.server.tsx");
+            const response: Response = await entry.default(
+              request,
+              "/src/entry.client.tsx",
+            );
+
+            if (!response.headers.get("Content-Type")?.includes("text/html"))
+              return send(response, outgoing);
+
+            const html = await server.transformIndexHtml(
+              incoming.url!,
+              await response.text(),
+            );
+            await send(
+              new Response(html, {
+                status: response.status,
+                headers: response.headers,
+              }),
+              outgoing,
+            );
+          };
+          void run().catch(next);
+        });
+      };
+    },
+  };
+
+  return [
+    application,
+    browserBoundary(),
+    ...(splitRoutes ? [lazyFiles(directory)] : []),
+    routerPlugin({ directory, framework: "preact" }),
+  ];
+}

package/.generated/vite/deployment.ts

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto";
+import type { Plugin } from "vite";
+
+/** Deployment manifest configuration. Serve the emitted file with Cache-Control: no-store. */
+export interface DeploymentPluginOptions {
+  /** Public URL, optionally on an asset host. Defaults to Vite base + smolter-manifest.json. */
+  manifestURL?: string;
+}
+
+/** Emit a build manifest and expose its identity through virtual:smolter/deployment. */
+export function deploymentPlugin(
+  options: DeploymentPluginOptions = {},
+): Plugin {
+  const version = randomUUID();
+  const virtualId = "\0virtual:smolter/deployment";
+  let enabled = false;
+  let manifestURL = "";
+
+  return {
+    name: "smolter-deployment",
+    configResolved(config) {
+      enabled = config.command === "build" && !config.build.ssr;
+      manifestURL =
+        options.manifestURL ?? `${config.base}smolter-manifest.json`;
+    },
+    resolveId(id) {
+      if (id === "virtual:smolter/deployment") return virtualId;
+    },
+    load(id) {
+      if (id !== virtualId) return;
+
+      const deployment = enabled ? { version, manifestURL } : null;
+
+      return `export default ${JSON.stringify(deployment)};`;
+    },
+    generateBundle() {
+      if (!enabled) return;
+
+      this.emitFile({
+        type: "asset",
+        fileName: "smolter-manifest.json",
+        source: JSON.stringify({ version }),
+      });
+    },
+  };
+}

package/{src/internal → .generated}/vite/index.ts

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
 import { flatRoutes } from "../files/index.ts";
 import { type Plugin, transformWithOxc } from "vite";
 import { configureTransport } from "./transport.ts";
@@ -185,11 +185,18 @@ export function routerPlugin({
       server.watcher.add(root);
 
       const refresh = (file: string) => {
-        if (!file.startsWith(`${root}/`)) return;
+        if (clientRoutes || serverRoutes) return;
 
-        const module = server.moduleGraph.getModuleById(virtualId);
+        const path = relative(root, file).replaceAll("\\", "/");
 
-        if (module) server.moduleGraph.invalidateModule(module);
+        if (!/^(?:[^/]+\.[jt]sx?|[^/]+\/route\.[jt]sx?)$/.test(path)) return;
+        if (path.endsWith(".d.ts")) return;
+
+        for (const environment of Object.values(server.environments)) {
+          const module = environment.moduleGraph.getModuleById(virtualId);
+
+          if (module) environment.moduleGraph.invalidateModule(module);
+        }
 
         server.ws.send({ type: "full-reload" });
       };

package/{src/preact-vite.ts → .generated/vite/preact.ts}

@@ -4,10 +4,10 @@ import type { Plugin } from "vite";
 import {
   routerPlugin as createPlugin,
   type FileRouterOptions,
-} from "./internal/vite/index.ts";
+} from "./index.ts";
 
-export * from "./internal/files/index.ts";
-export type { FileRouterOptions } from "./internal/vite/index.ts";
+export * from "../files/index.ts";
+export type { FileRouterOptions } from "./index.ts";
 
 /** Configure flat routes and server transport for Preact. */
 export function routerPlugin(options: FileRouterOptions = {}): Plugin {
@@ -16,3 +16,14 @@ export function routerPlugin(options: FileRouterOptions = {}): Plugin {
 
 /** File routing is the default; this alias keeps configuration explicit. */
 export const fileRouter = routerPlugin;
+
+export type { ApplicationOptions } from "./application/vite.ts";
+export {
+  applicationPlugins,
+  preactConfig,
+} from "./application/vite.ts";
+
+export {
+  type DeploymentPluginOptions,
+  deploymentPlugin,
+} from "./deployment.ts";

package/{src/react-vite.ts → .generated/vite/react.ts}

@@ -4,10 +4,10 @@ import type { Plugin } from "vite";
 import {
   routerPlugin as createPlugin,
   type FileRouterOptions,
-} from "./internal/vite/index.ts";
+} from "./index.ts";
 
-export * from "./internal/files/index.ts";
-export type { FileRouterOptions } from "./internal/vite/index.ts";
+export * from "../files/index.ts";
+export type { FileRouterOptions } from "./index.ts";
 
 /** Configure flat routes and server transport for React. */
 export function routerPlugin(options: FileRouterOptions = {}): Plugin {
@@ -16,3 +16,8 @@ export function routerPlugin(options: FileRouterOptions = {}): Plugin {
 
 /** File routing is the default; this alias keeps configuration explicit. */
 export const fileRouter = routerPlugin;
+
+export {
+  type DeploymentPluginOptions,
+  deploymentPlugin,
+} from "./deployment.ts";

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 0.3.1
+
+- Refresh browser and SSR file-route discovery on additions, renames and removals; preserve normal Vite HMR for colocated helpers and components.
+
+- Add optional production deployment manifests through `deploymentPlugin` for both React and Preact Vite integrations.
+- Add `watchDeployment` to both client entrypoints: check before navigation and Back/Forward, recover stale Vite chunks after confirmed build changes, and preserve the requested URL.
+- Skip hash-only links, development builds and SSR; bound failed checks and prevent repeated reloads. Keep routing-only bundles unchanged.
+- Document production cache headers, CDN/application-specific manifest paths, unsaved state and rollout limitations.
+
+## 0.3.0
+
+### Migration from 0.2.0
+
+- **Breaking:** use `createDataRouter` for loaders, actions, fetchers and revalidation. `createRouter` now creates a navigation-only router. Framework imports remain `@kasperrt/smolter/react` and `@kasperrt/smolter/preact`.
+- **Breaking:** the Preact adapter requires Preact 11.0.1 or newer.
+- Optional Preact application helpers use explicit `/preact/client`, `/preact/document`, `/preact/lazy-route` and `/preact/server` entry points. Server code and Vite tooling remain outside browser bundles.
+
+### Added
+
+- Navigation-only engines that tree-shake out data handling: 1,245 B React and 1,405 B Preact gzip with the documented routing subset.
+- Preact application SSR and hydration, lazy flat routes, retained route content while loading, prefetching, and controlled view transitions.
+- Express-compatible request/response helpers and documented Vite virtual-module and entry-file contracts.
+- Route-targeted revalidation, including explicitly configured root data, and independent fetcher reads.
+- Optional React resource hooks through `/react/data`.
+- Detailed guides for routing, handlers, forms, fetchers, SSR, Express, bundle sizes and every public export.
+
+### Fixed and improved
+
+- Serialize Preact fetcher GET submissions into the destination query without navigating or invoking an action.
+- Share form submission and navigation interception logic between adapters.
+- Preserve cancellation, error hydration and stable data during navigation and revalidation.
+- Separate example handler and boundary files; use route-appropriate loading placeholders.
+- Build the publishable package and site through Vite with preserved module boundaries, production smoke tests and 100% implementation line coverage.
+- Generate honest size comparisons for routing-only, data, transport and application entry points.
+
+## 0.2.0
+
+- Breaking: choose `@kasperrt/smolter/react` or `@kasperrt/smolter/preact` for routing APIs and types.
+- Move optional transport, SSR, and build tools under the selected renderer’s `/client`, `/server`, and `/vite` subpaths. Remove root and top-level core/client/server/files/vite exports.
+- Keep browser-safe helpers in `@kasperrt/smolter/utils`.
+- Verify unused exports and server/build modules are removed from browser bundles.
+
+## 0.0.1
+
+- First stable release of `@kasperrt/smolter` for React and Preact.
+- Typed loaders, actions, client handlers, fetchers, and controlled revalidation.
+- Manual and flat file routes, server transport, SSR, and hydration.
+- Tokenless npm and JSR publishing through tested GitHub Actions.
+
+## 0.0.1-rc.2
+
+- Use `@kasperrt/smolter` explicitly in every public import and generated route module.
+- Remove the unscoped install alias from examples and documentation.
+
+## 0.0.1-rc.1
+
+- Typed React and Preact routing with loaders, actions, and independent fetchers.
+- Server handlers with optional clientLoader and clientAction call-through.
+- Manual route tables and optional flat file routing.
+- Server rendering, hydration, and controlled loader revalidation.
+- Four standalone examples and shared UI.