feat(router): layered pagesDirs so frameworks can ship default views

chrisbbreuer · claude · chrisbbreuer · commit fdc35cbb9311 · 2026-05-05T16:10:31.000-07:00
Apps that build on top of a framework (storefronts, dashboards, blogs)
want to inherit a stack of default views — cart, checkout, orders,
welcome emails — and override only the ones they care about. Until now
the Router accepted exactly one `pagesDir`, so a project either took
the framework defaults wholesale (by symlinking) or copied every
default into its own views directory just to keep custom routes.

This adds an ordered `pagesDirs` to RouterConfig. The Router scans each
root in order, and the first match wins per pattern — so a user's
`resources/views/cart.stx` shadows the framework's
`storage/framework/defaults/resources/views/cart.stx`, and any default
view the user hasn't customized still resolves through the second root.

`bun-plugin/src/serve.ts` now passes ALL `patterns` through to the
Router, instead of only the first one. The on-disk file walker
(`discoverFiles`) already aggregated across all patterns, but the
generated `.stx/routes.ts` manifest and the route-name type emitter
were dropping every pattern after the first — so framework default
pages worked sometimes but not predictably.

Backwards compatible: `pagesDir` still works as before when set alone.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/bun-plugin/src/serve.ts b/packages/bun-plugin/src/serve.ts
@@ -474,11 +474,15 @@ export async function serve(options: ServeOptions): Promise<void> {
     pageMiddlewarePatterns.length = 0
     await Promise.all(files.map(f => detectPageMiddleware(f)))
 
-    // Generate route manifest and type declarations into .stx/
+    // Generate route manifest and type declarations into .stx/.
+    // Pass ALL patterns as a stack of page roots so frameworks can ship
+    // default views (e.g. cart, checkout, orders) and apps can override
+    // any of them by dropping a file with the same path into their own
+    // `resources/views`. The first matching root wins per pattern.
     try {
       const { Router } = await import('stx-router')
-      const pagesDir = patterns[0]?.replace(/\/$/, '') || 'pages'
-      const router = new Router(process.cwd(), { pagesDir })
+      const pagesDirs = patterns.map(p => p.replace(/\/$/, '')).filter(Boolean)
+      const router = new Router(process.cwd(), { pagesDirs })
       console.log(`[stx] Generated ${router.routes.length} routes → .stx/routes.ts`)
     }
     catch (e) {
diff --git a/packages/router/src/file-router.ts b/packages/router/src/file-router.ts
@@ -45,29 +45,51 @@ function scanDirectory(dir: string, extensions: string[]): string[] {
 export class Router {
   routes: Route[]
   private pagesDir: string
+  private pagesDirs: string[]
   private config: RouterConfig
 
   constructor(baseDir: string, config: RouterConfig = {}) {
     this.config = config
-    this.pagesDir = path.resolve(baseDir, config.pagesDir || 'pages')
-    const extensions = config.extensions || ['.stx']
 
-    const files = scanDirectory(this.pagesDir, extensions)
+    // Resolve the stack of page roots. `pagesDirs` wins when both are
+    // set; otherwise fall back to the single-root `pagesDir`. Each
+    // entry is resolved relative to `baseDir`.
+    const rawDirs = (config.pagesDirs && config.pagesDirs.length > 0)
+      ? config.pagesDirs
+      : [config.pagesDir || 'pages']
+    this.pagesDirs = rawDirs.map(d => path.resolve(baseDir, d))
+    // For backwards compatibility, `pagesDir` keeps pointing at the
+    // first root — that's the user-facing root for codegen output.
+    this.pagesDir = this.pagesDirs[0]
 
-    this.routes = files.map((filePath) => {
-      const pattern = filePathToPattern(filePath, this.pagesDir)
-      const { regex, params } = patternToRegex(pattern)
-      const layouts = config.layouts !== false ? resolveLayoutChain(filePath, this.pagesDir) : []
+    const extensions = config.extensions || ['.stx']
 
-      return {
-        pattern,
-        regex,
-        params,
-        filePath,
-        isDynamic: params.length > 0,
-        layout: layouts.length > 0 ? layouts[layouts.length - 1] : undefined,
+    // Scan each root and bucket files by their resulting URL pattern.
+    // Earlier roots win, so a user's `resources/views/cart.stx` shadows
+    // the framework's `storage/framework/defaults/resources/views/cart.stx`.
+    const seenPatterns = new Set<string>()
+    this.routes = []
+    for (const dir of this.pagesDirs) {
+      const files = scanDirectory(dir, extensions)
+      for (const filePath of files) {
+        const pattern = filePathToPattern(filePath, dir)
+        if (seenPatterns.has(pattern))
+          continue
+        seenPatterns.add(pattern)
+
+        const { regex, params } = patternToRegex(pattern)
+        const layouts = config.layouts !== false ? resolveLayoutChain(filePath, dir) : []
+
+        this.routes.push({
+          pattern,
+          regex,
+          params,
+          filePath,
+          isDynamic: params.length > 0,
+          layout: layouts.length > 0 ? layouts[layouts.length - 1] : undefined,
+        })
       }
-    })
+    }
 
     // Sort: static before dynamic, more segments first
     this.routes.sort((a, b) => {
diff --git a/packages/router/src/types.ts b/packages/router/src/types.ts
@@ -15,7 +15,24 @@ export interface RouteMatch {
 }
 
 export interface RouterConfig {
+  /**
+   * Single page root. Resolved relative to `baseDir`. Default: `'pages'`.
+   *
+   * Use `pagesDirs` instead when you want a stack of roots (e.g. user
+   * views on top, framework defaults underneath).
+   */
   pagesDir?: string
+  /**
+   * Stack of page roots, scanned in order. The first match for any
+   * given route pattern wins, so earlier entries override later ones.
+   *
+   * Useful for app frameworks that ship default views (cart, checkout,
+   * orders) but want apps to override individual pages by dropping a
+   * file with the same name into their own views directory.
+   *
+   * If both `pagesDir` and `pagesDirs` are set, `pagesDirs` takes precedence.
+   */
+  pagesDirs?: string[]
   extensions?: string[]
   layouts?: boolean
   middleware?: boolean
diff --git a/packages/router/test/layered-roots.test.ts b/packages/router/test/layered-roots.test.ts
@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { Router } from '../src/file-router'
+
+/**
+ * Layered page roots: the Router accepts an ordered stack of page
+ * directories. Earlier roots shadow later ones for the same pattern,
+ * which lets a framework ship default views (cart, checkout, orders)
+ * and let apps override them just by dropping a file with the same
+ * relative path into their own views directory.
+ */
+describe('Router with layered pagesDirs', () => {
+  let baseDir: string
+  let userDir: string
+  let defaultsDir: string
+
+  beforeEach(() => {
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'stx-router-roots-'))
+    userDir = path.join(baseDir, 'resources', 'views')
+    defaultsDir = path.join(baseDir, 'storage', 'framework', 'defaults', 'resources', 'views')
+    fs.mkdirSync(userDir, { recursive: true })
+    fs.mkdirSync(path.join(defaultsDir, 'orders'), { recursive: true })
+  })
+
+  afterEach(() => {
+    fs.rmSync(baseDir, { recursive: true, force: true })
+  })
+
+  function writeView(dir: string, relPath: string, body = '<html></html>'): string {
+    const full = path.join(dir, relPath)
+    fs.mkdirSync(path.dirname(full), { recursive: true })
+    fs.writeFileSync(full, body)
+    return full
+  }
+
+  it('serves a default-only page from the second root', () => {
+    writeView(userDir, 'index.stx')
+    writeView(defaultsDir, 'cart.stx')
+    writeView(defaultsDir, 'orders/[id].stx')
+
+    const router = new Router(baseDir, {
+      pagesDirs: [
+        path.relative(baseDir, userDir),
+        path.relative(baseDir, defaultsDir),
+      ],
+    })
+
+    const patterns = router.routes.map(r => r.pattern).sort()
+    expect(patterns).toContain('/cart')
+    expect(patterns).toContain('/orders/:id')
+    expect(patterns).toContain('/')
+  })
+
+  it('first root shadows the second for the same pattern', () => {
+    const userIndex = writeView(userDir, 'index.stx', '<!-- user -->')
+    writeView(defaultsDir, 'index.stx', '<!-- defaults -->')
+
+    const router = new Router(baseDir, {
+      pagesDirs: [
+        path.relative(baseDir, userDir),
+        path.relative(baseDir, defaultsDir),
+      ],
+    })
+
+    const indexRoute = router.routes.find(r => r.pattern === '/')
+    expect(indexRoute).toBeDefined()
+    expect(indexRoute!.filePath).toBe(userIndex)
+
+    // The shadowed default must NOT also be in the route list — that
+    // would duplicate `/` and the wrong one might match first.
+    const indexes = router.routes.filter(r => r.pattern === '/')
+    expect(indexes.length).toBe(1)
+  })
+
+  it('falls back to second root for patterns not present in the first', () => {
+    writeView(userDir, 'index.stx')
+    const defaultCart = writeView(defaultsDir, 'cart.stx', '<!-- defaults -->')
+
+    const router = new Router(baseDir, {
+      pagesDirs: [
+        path.relative(baseDir, userDir),
+        path.relative(baseDir, defaultsDir),
+      ],
+    })
+
+    const cartRoute = router.routes.find(r => r.pattern === '/cart')
+    expect(cartRoute).toBeDefined()
+    expect(cartRoute!.filePath).toBe(defaultCart)
+  })
+
+  it('preserves backwards-compat single-root pagesDir', () => {
+    writeView(userDir, 'about.stx')
+
+    const router = new Router(baseDir, {
+      pagesDir: path.relative(baseDir, userDir),
+    })
+
+    expect(router.routes.map(r => r.pattern)).toEqual(['/about'])
+  })
+
+  it('matches /cart against a defaults-only view', () => {
+    writeView(userDir, 'index.stx')
+    writeView(defaultsDir, 'cart.stx')
+
+    const router = new Router(baseDir, {
+      pagesDirs: [
+        path.relative(baseDir, userDir),
+        path.relative(baseDir, defaultsDir),
+      ],
+    })
+
+    const match = router.match('/cart')
+    expect(match).not.toBeNull()
+    expect(match!.route.pattern).toBe('/cart')
+  })
+
+  it('handles missing first root gracefully', () => {
+    writeView(defaultsDir, 'cart.stx')
+
+    const router = new Router(baseDir, {
+      pagesDirs: [
+        'does/not/exist',
+        path.relative(baseDir, defaultsDir),
+      ],
+    })
+
+    expect(router.routes.map(r => r.pattern)).toContain('/cart')
+  })
+})
