Skip to content

CONCEPT Cited by 1 source

File-based routing vs bare-HTTP framework taxonomy

File-based routing vs bare-HTTP framework taxonomy is the bifurcation axis that determines how a framework exposes handlers as HTTP endpoints — and therefore what the integration pattern for a cross-framework SDK must look like on its runtime side.

Canonical framing from Vercel's 2026-04-21 WDK post: "Building multiple integrations revealed that frameworks fall into two categories."

The two families

File-based-routing frameworks

"Next.js, SvelteKit, Nuxt" — and by extension Astro, Remix, TanStack Start. The framework ships with file-system-as-route-table semantics: drop a file with a framework-recognised name (+server.js in SvelteKit, route.ts/page.tsx in Next.js) into a framework-recognised directory, and the framework automatically discovers it as an HTTP endpoint at startup.

Integration strategy for an SDK like WDK:

  • Build-time: output generated handler files into the right framework-specific directory (e.g. app/.well-known/workflow/v1 for Next.js, src/routes/.well-known/workflow/v1 for SvelteKit).
  • Runtime: framework's auto-discovery does the work. No manual wiring needed, though each framework requires "different patches for how endpoints are defined and handled."

Bare-HTTP / HTTP-server frameworks

"Express, Hono" — and Fastify, Koa, polka. "These frameworks don't ship with a build system, i.e. they don't have a bundler, and just expose a bare HTTP server." There is no file-based routing to output into; the app author writes app.get("/path", handler) imperatively.

Integration strategy requires a build-system shim:

  • WDK uses Nitro — esbuild bundles the workflows, then Nitro mounts them as virtual handlers.
  • Runtime: Nitro wraps the app's HTTP server and injects the virtual handlers, exposing workflow endpoints as if they were part of the user's routes.

Canonical pattern: patterns/virtual-handler-via-nitro-for-bundlerless-frameworks.

Why the taxonomy is load-bearing

The taxonomy choice shapes the runtime half of two-phase framework integration:

  • File-based-routing → runtime bridge is "put the file here".
  • Bare-HTTP → runtime bridge is "inject handlers at runtime via a shim".

The build-time half (handler generation via SWC + esbuild) stays the same in both cases — only the runtime exposure mechanism differs. This is the structural reason one WDK SWC plugin can serve 8 frameworks: the build-time code is shared, the runtime adapter bifurcates along this taxonomy.

Vite as meta-axis

Vite-based frameworks (SvelteKit, Astro, Nuxt, vinext) are a subfamily of file-based-routing: they all share Vite's plugin system + HMR + file-based routing. Verbatim: "This meant most of the integration code for plugin registration, HMR configuration, and client transforms was nearly identical across them. We built the core Vite integration once, then adapted it for each framework's specific routing patterns."

Seen in

Last updated · 476 distilled / 1,218 read