Skip to content

Deprecate and remove @stacksjs/router (now a thin wrapper around @stacksjs/bun-router) #1836

@glennmichael123

Description

@glennmichael123

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

  1. Land request context + named-route URLs in bun-router upstream — see stacksjs/bun-router#874.
  2. 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.
  3. Delete storage/framework/core/router/ workspace package.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions