storage/framework/core/router/ (@stacksjs/router) was originally a Stacks-specific layer over bun-router that added action-string handlers and route-file loading. With the current @stacksjs/bun-router@0.0.5+, most of those features are now upstream:
- String action handlers (
'Actions/Foo') — already in bun-router (handler-resolver.ts:92)
- File-based routing — already in bun-router (
file-based-routing.ts)
- Route grouping, class handlers, response factory,
cors, Middleware, rate limiting — all in bun-router
The wrapper now provides essentially:
- A pre-instantiated
route singleton (vs. bun-router's router)
runWithRequest / request() AsyncLocalStorage helpers
- Named-route
url(name, params) generation
- An object-shaped routes-registry loader (
app/Routes.ts map → file imports)
trackQuery for the debug error page
- Action
validations schema hook
Proposal
- Land request context + named-route URLs in bun-router upstream — see stacksjs/bun-router#874.
- Once those land, do the migration in this repo:
- Rewrite
~22 import sites from @stacksjs/router → @stacksjs/bun-router for pass-throughs (Router, cors, response, Middleware, Request type, rate-limit helpers, serve).
- Switch the remaining ~8 sites that use context/url to the new bun-router APIs.
- Keep
trackQuery and Action validations as small Stacks-side helpers (they're project-specific; see notes in stacksjs/bun-router#874 for rationale).
- Replace the object-shaped
app/Routes.ts registry with a tiny app-side loader, OR drop the registry pattern and import route files directly in dev/api.ts. Either works.
- Delete
storage/framework/core/router/ workspace package.
- Update CLI scaffolds (
routes/api.ts template, dev-server entrypoints, etc.) to import from @stacksjs/bun-router directly.
Why now
- The two packages overlapping has caused real pain:
routes/api.ts defaults to import { route } from '@stacksjs/bun-router', which doesn't export route — a user-visible 404 on every endpoint of a fresh app (see #1835).
- Type-resolution edge cases in the wrapper bleed into editor errors (
TS7034 Variable 'route' implicitly has type 'any') when bun-router's published .d.ts is incomplete (see stacksjs/dtsx#3090 for the related dts-emission bug).
- Deprecating the wrapper removes the ambiguity and reduces maintenance surface.
Migration risk
Low-medium. Mechanical for pass-through imports. The substantive work is just porting ~70 LOC of glue into bun-router (request context + named URLs) and ~80 LOC of stacks-specific helpers (validations + trackQuery + optional registry loader) staying in this repo. No runtime behavior change for end users.
Blocked on
stacksjs/bun-router#874 — request context + named-route URL helpers landing upstream.
storage/framework/core/router/(@stacksjs/router) was originally a Stacks-specific layer over bun-router that added action-string handlers and route-file loading. With the current@stacksjs/bun-router@0.0.5+, most of those features are now upstream:'Actions/Foo') — already in bun-router (handler-resolver.ts:92)file-based-routing.ts)cors,Middleware, rate limiting — all in bun-routerThe wrapper now provides essentially:
routesingleton (vs. bun-router'srouter)runWithRequest/request()AsyncLocalStorage helpersurl(name, params)generationapp/Routes.tsmap → file imports)trackQueryfor the debug error pagevalidationsschema hookProposal
~22import sites from@stacksjs/router→@stacksjs/bun-routerfor pass-throughs (Router,cors,response,Middleware,Requesttype, rate-limit helpers,serve).trackQueryand Actionvalidationsas small Stacks-side helpers (they're project-specific; see notes in stacksjs/bun-router#874 for rationale).app/Routes.tsregistry with a tiny app-side loader, OR drop the registry pattern and import route files directly indev/api.ts. Either works.storage/framework/core/router/workspace package.routes/api.tstemplate, dev-server entrypoints, etc.) to import from@stacksjs/bun-routerdirectly.Why now
routes/api.tsdefaults toimport { route } from '@stacksjs/bun-router', which doesn't exportroute— a user-visible 404 on every endpoint of a fresh app (see #1835).TS7034 Variable 'route' implicitly has type 'any') when bun-router's published.d.tsis incomplete (see stacksjs/dtsx#3090 for the related dts-emission bug).Migration risk
Low-medium. Mechanical for pass-through imports. The substantive work is just porting ~70 LOC of glue into bun-router (request context + named URLs) and ~80 LOC of stacks-specific helpers (validations + trackQuery + optional registry loader) staying in this repo. No runtime behavior change for end users.
Blocked on
stacksjs/bun-router#874 — request context + named-route URL helpers landing upstream.