feat: built-in file-system routing (experimental)

[uhyo]

Summary

Adds built-in file-system routing to @funstack/static, so users no longer have to wire up routing in userland (as in the previous example-fs-routing). Pages discovered under a configurable directory are mapped to routes and rendered with FUNSTACK Router, generating one static HTML file per route.

This feature is marked experimental and is not yet covered by semantic versioning.

Usage

// vite.config.ts
funstackStatic({
  fsRoutes: {
    dir: "./src/pages",      // default "./src/pages"
    root: "./src/root.tsx",  // HTML shell
    adapter: "./src/my-adapter.ts", // optional; defaults to nextRoutes()
  },
})

The new fsRoutes mode is mutually exclusive with root+app (single-entry) and entries (multiple entries). The plugin synthesizes the entries module (emitting import.meta.glob in a virtual module that Vite transforms), so the user writes no glob themselves.

Design

• Router is fixed to FUNSTACK Router — @funstack/router is an optional peer dependency, required only when using this feature.
• Convention is pluggable via an adapter (FsRoutesAdapter) — the directory/file-name convention is decoupled from the framework's tree→routes/entries logic.
• Built-in Next.js-like adapter (nextRoutes) supporting page/layout files, dynamic [param] and catch-all [...param] segments, and (group) route groups.
• Dynamic routes are statically generated via a generateStaticParams export (Next.js-like); pages receive resolved params as a prop.
• The runtime primitive createFsRoutesEntries and nextRoutes are exported from @funstack/static/fs-routes as an escape hatch for fully custom routing.

Known limitation

Because static hosting serves one pre-rendered RSC payload per page, soft client-side navigation between different values of the same dynamic route reflects the params of the initially-loaded page. Loading a dynamic URL directly (or via the SPA fallback) always renders correct params, and static routes + layouts navigate fully on the client. This is documented in the guide.

Testing

• Unit tests for the adapter, static-path collection, and glob-prefix stripping (51 passed).
• New e2e fixture (fixture-fs-routing) + build/dev specs wired into Playwright.
• example-fs-routing converted to the built-in feature.
• Docs updated: new File-System Routing guide + fsRoutes option in the API reference.
• build, typecheck, lint, format:check all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_012L8PCU7xhNXfuepS7eKzro

---

Generated by Claude Code