one 1.2.75 → 1.2.76

package/src/server/oneServe.ts

@@ -129,11 +129,15 @@ export async function oneServe(
     async handleLoader({ route, loaderProps }) {
       // Use lazy import if available (workers), otherwise dynamic import (Node.js)
       // For workers, look up by routeFile (original file path like "./dynamic/[id]+ssr.tsx")
-      // For Node.js, use route.file which may be loaderServerPath
+      // For Node.js, use route.file which may be loaderServerPath (already includes dist/server)
       const routeFile = (route as any).routeFile || route.file
+      // route.file may already include dist/server if it came from loaderServerPath
+      const serverPath = route.file.includes('dist/server')
+        ? route.file
+        : join('./', 'dist/server', route.file)
       const exports = options?.lazyRoutes?.pages?.[routeFile]
         ? await options.lazyRoutes.pages[routeFile]()
-        : await import(toAbsolute(join('./', 'dist/server', route.file)))
+        : await import(toAbsolute(serverPath))
 
       const { loader } = exports
 
@@ -163,17 +167,92 @@ export async function oneServe(
             ? await options.lazyRoutes.pages[route.file]()
             : await import(toAbsolute(buildInfo.serverJsPath))
 
-          let loaderData
+          // helper to import and run a single loader
+          async function runLoader(
+            routeId: string,
+            serverPath: string | undefined,
+            lazyKey?: string
+          ): Promise<{ loaderData: unknown; routeId: string }> {
+            if (!serverPath && !lazyKey) {
+              return { loaderData: undefined, routeId }
+            }
+
+            try {
+              // serverPath may already include dist/server if it came from buildInfo.serverJsPath
+              const pathToResolve = serverPath || lazyKey || ''
+              const resolvedPath = pathToResolve.includes('dist/server')
+                ? pathToResolve
+                : join('./', 'dist/server', pathToResolve)
+
+              const routeExported = lazyKey
+                ? options?.lazyRoutes?.pages?.[lazyKey]
+                  ? await options.lazyRoutes.pages[lazyKey]()
+                  : await import(toAbsolute(resolvedPath))
+                : await import(toAbsolute(serverPath!))
+
+              const loaderData = await routeExported?.loader?.(loaderProps)
+              return { loaderData, routeId }
+            } catch (err) {
+              // if a loader throws a Response (redirect), re-throw it
+              if (isResponse(err)) {
+                throw err
+              }
+              console.error(`[one] Error running loader for ${routeId}:`, err)
+              return { loaderData: undefined, routeId }
+            }
+          }
+
+          // collect layout loaders to run in parallel
+          const layoutRoutes = route.layouts || []
+          const layoutLoaderPromises = layoutRoutes.map((layout: any) => {
+            // layouts may have loaderServerPath set from build, or we can try contextKey
+            const serverPath = layout.loaderServerPath || layout.contextKey
+            return runLoader(layout.contextKey, serverPath, layout.contextKey)
+          })
+
+          // run page loader
+          const pageLoaderPromise = runLoader(
+            route.file,
+            buildInfo.serverJsPath,
+            route.file
+          )
+
+          // wait for all loaders in parallel
+          let layoutResults: Array<{ loaderData: unknown; routeId: string }>
+          let pageResult: { loaderData: unknown; routeId: string }
+
           try {
-            loaderData = await exported.loader?.(loaderProps)
-          } catch (loaderErr) {
-            // Handle thrown responses (e.g., redirect) from loader
-            if (isResponse(loaderErr)) {
-              return loaderErr
+            ;[layoutResults, pageResult] = await Promise.all([
+              Promise.all(layoutLoaderPromises),
+              pageLoaderPromise,
+            ])
+          } catch (err) {
+            // Handle thrown responses (e.g., redirect) from any loader
+            if (isResponse(err)) {
+              return err
             }
-            throw loaderErr
+            throw err
           }
 
+          // build matches array (layouts + page)
+          const matches: One.RouteMatch[] = [
+            ...layoutResults.map((result) => ({
+              routeId: result.routeId,
+              pathname: loaderProps?.path || '/',
+              params: loaderProps?.params || {},
+              loaderData: result.loaderData,
+            })),
+            {
+              routeId: pageResult.routeId,
+              pathname: loaderProps?.path || '/',
+              params: loaderProps?.params || {},
+              loaderData: pageResult.loaderData,
+            },
+          ]
+
+          // for backwards compat, loaderData is still the page's loader data
+          const loaderData = pageResult.loaderData
+
           const headers = new Headers()
           headers.set('content-type', 'text/html')
 
@@ -194,6 +273,7 @@ export async function oneServe(
             deferredPreloads: buildInfo.deferredPreloads,
             css: buildInfo.css,
             cssContents: buildInfo.cssContents,
+            matches,
           })
 
           return new Response(rendered, {

package/src/types.ts

@@ -36,4 +36,9 @@ export type RenderAppProps = {
   loaderData?: any
   loaderProps?: LoaderProps
   routePreloads?: Record<string, string>
+  /**
+   * All matched routes with their loader data.
+   * Ordered from root layout to leaf page (parent → child).
+   */
+  matches?: One.RouteMatch[]
 }

package/src/useMatches.test.ts

@@ -0,0 +1,317 @@
+import { describe, expect, it } from 'vitest'
+import type { One } from './vite/types'
+import { setClientMatches } from './useMatches'
+
+describe('useMatches', () => {
+  describe('setClientMatches', () => {
+    it('should update client matches without errors', () => {
+      const matches: One.RouteMatch[] = [
+        {
+          routeId: '/_layout',
+          pathname: '/',
+          params: {},
+          loaderData: { title: 'Root' },
+        },
+        {
+          routeId: '/page',
+          pathname: '/page',
+          params: {},
+          loaderData: { content: 'Page content' },
+        },
+      ]
+
+      // should not throw
+      expect(() => setClientMatches(matches)).not.toThrow()
+    })
+
+    it('should accept empty matches array', () => {
+      expect(() => setClientMatches([])).not.toThrow()
+    })
+  })
+
+  describe('type safety', () => {
+    it('should have correct RouteMatch type', () => {
+      const match: One.RouteMatch = {
+        routeId: 'test',
+        pathname: '/test',
+        params: { id: '123' },
+        loaderData: { foo: 'bar' },
+      }
+
+      expect(match.routeId).toBe('test')
+      expect(match.pathname).toBe('/test')
+      expect(match.params.id).toBe('123')
+      expect(match.loaderData).toEqual({ foo: 'bar' })
+    })
+
+    it('should allow string[] params', () => {
+      const match: One.RouteMatch = {
+        routeId: 'test',
+        pathname: '/test',
+        params: { slugs: ['a', 'b', 'c'] },
+        loaderData: null,
+      }
+
+      expect(match.params.slugs).toEqual(['a', 'b', 'c'])
+    })
+
+    it('should allow undefined loaderData', () => {
+      const match: One.RouteMatch = {
+        routeId: 'test',
+        pathname: '/test',
+        params: {},
+        loaderData: undefined,
+      }
+
+      expect(match.loaderData).toBeUndefined()
+    })
+  })
+})
+
+describe('RouteMatch ordering', () => {
+  it('matches should be ordered parent to child (root layout first)', () => {
+    const matches: One.RouteMatch[] = [
+      { routeId: '/_layout', pathname: '/', params: {}, loaderData: { level: 'root' } },
+      {
+        routeId: '/docs/_layout',
+        pathname: '/docs',
+        params: {},
+        loaderData: { level: 'docs' },
+      },
+      {
+        routeId: '/docs/intro',
+        pathname: '/docs/intro',
+        params: {},
+        loaderData: { level: 'page' },
+      },
+    ]
+
+    // root layout should be first
+    expect(matches[0].routeId).toBe('/_layout')
+    expect((matches[0].loaderData as any).level).toBe('root')
+
+    // docs layout should be second
+    expect(matches[1].routeId).toBe('/docs/_layout')
+    expect((matches[1].loaderData as any).level).toBe('docs')
+
+    // page should be last
+    expect(matches[2].routeId).toBe('/docs/intro')
+    expect((matches[2].loaderData as any).level).toBe('page')
+  })
+
+  it('last match should be the current page', () => {
+    const matches: One.RouteMatch[] = [
+      { routeId: '/_layout', pathname: '/', params: {}, loaderData: {} },
+      {
+        routeId: '/page',
+        pathname: '/page',
+        params: { id: '123' },
+        loaderData: { title: 'Page' },
+      },
+    ]
+
+    const pageMatch = matches[matches.length - 1]
+    expect(pageMatch.routeId).toBe('/page')
+    expect((pageMatch.loaderData as any).title).toBe('Page')
+  })
+})
+
+describe('setClientMatches reactivity', () => {
+  it('should notify listeners when matches change', () => {
+    let notifyCount = 0
+
+    // simulate a listener (like what useSyncExternalStore would use)
+    const listener = () => {
+      notifyCount++
+    }
+
+    // manually test the subscription mechanism
+    const matches1: One.RouteMatch[] = [
+      { routeId: '/page1', pathname: '/page1', params: {}, loaderData: {} },
+    ]
+    const matches2: One.RouteMatch[] = [
+      { routeId: '/page2', pathname: '/page2', params: {}, loaderData: {} },
+    ]
+
+    // first call
+    setClientMatches(matches1)
+    // no listener yet, so notifyCount is still 0
+
+    // second call
+    setClientMatches(matches2)
+    // still no listener
+
+    expect(notifyCount).toBe(0) // we didn't subscribe
+  })
+
+  it('should handle multiple sequential updates', () => {
+    const matches1: One.RouteMatch[] = [
+      { routeId: '/a', pathname: '/a', params: {}, loaderData: { n: 1 } },
+    ]
+    const matches2: One.RouteMatch[] = [
+      { routeId: '/b', pathname: '/b', params: {}, loaderData: { n: 2 } },
+    ]
+    const matches3: One.RouteMatch[] = [
+      { routeId: '/c', pathname: '/c', params: {}, loaderData: { n: 3 } },
+    ]
+
+    // should not throw on rapid updates
+    expect(() => {
+      setClientMatches(matches1)
+      setClientMatches(matches2)
+      setClientMatches(matches3)
+    }).not.toThrow()
+  })
+})
+
+describe('RouteMatch with dynamic params', () => {
+  it('should handle single dynamic param', () => {
+    const match: One.RouteMatch = {
+      routeId: '/users/[id]',
+      pathname: '/users/123',
+      params: { id: '123' },
+      loaderData: { user: { name: 'John' } },
+    }
+
+    expect(match.params.id).toBe('123')
+  })
+
+  it('should handle multiple dynamic params', () => {
+    const match: One.RouteMatch = {
+      routeId: '/users/[userId]/posts/[postId]',
+      pathname: '/users/123/posts/456',
+      params: { userId: '123', postId: '456' },
+      loaderData: { post: { title: 'Hello' } },
+    }
+
+    expect(match.params.userId).toBe('123')
+    expect(match.params.postId).toBe('456')
+  })
+
+  it('should handle catch-all params', () => {
+    const match: One.RouteMatch = {
+      routeId: '/docs/[...slug]',
+      pathname: '/docs/getting-started/intro',
+      params: { slug: ['getting-started', 'intro'] },
+      loaderData: { doc: { content: 'Hello' } },
+    }
+
+    expect(match.params.slug).toEqual(['getting-started', 'intro'])
+  })
+})
+
+describe('RouteMatch loaderData scenarios', () => {
+  it('should handle complex nested loaderData', () => {
+    const match: One.RouteMatch = {
+      routeId: '/dashboard',
+      pathname: '/dashboard',
+      params: {},
+      loaderData: {
+        user: {
+          id: 1,
+          profile: {
+            name: 'John',
+            settings: {
+              theme: 'dark',
+              notifications: true,
+            },
+          },
+        },
+        posts: [
+          { id: 1, title: 'Post 1' },
+          { id: 2, title: 'Post 2' },
+        ],
+      },
+    }
+
+    const data = match.loaderData as any
+    expect(data.user.profile.settings.theme).toBe('dark')
+    expect(data.posts).toHaveLength(2)
+  })
+
+  it('should handle null loaderData', () => {
+    const match: One.RouteMatch = {
+      routeId: '/empty',
+      pathname: '/empty',
+      params: {},
+      loaderData: null,
+    }
+
+    expect(match.loaderData).toBeNull()
+  })
+
+  it('should handle array loaderData', () => {
+    const match: One.RouteMatch = {
+      routeId: '/list',
+      pathname: '/list',
+      params: {},
+      loaderData: [1, 2, 3, 4, 5],
+    }
+
+    expect(match.loaderData).toEqual([1, 2, 3, 4, 5])
+  })
+
+  it('should handle primitive loaderData', () => {
+    const match: One.RouteMatch = {
+      routeId: '/count',
+      pathname: '/count',
+      params: {},
+      loaderData: 42,
+    }
+
+    expect(match.loaderData).toBe(42)
+  })
+})
+
+describe('finding matches', () => {
+  const createMatches = (): One.RouteMatch[] => [
+    { routeId: '/_layout', pathname: '/', params: {}, loaderData: { root: true } },
+    {
+      routeId: '/docs/_layout',
+      pathname: '/docs',
+      params: {},
+      loaderData: { navItems: ['intro', 'guide'] },
+    },
+    {
+      routeId: '/docs/[slug]',
+      pathname: '/docs/intro',
+      params: { slug: 'intro' },
+      loaderData: { title: 'Introduction', headings: ['h1', 'h2'] },
+    },
+  ]
+
+  it('should find match by exact routeId', () => {
+    const matches = createMatches()
+    const found = matches.find((m) => m.routeId === '/docs/_layout')
+
+    expect(found).toBeDefined()
+    expect((found!.loaderData as any).navItems).toEqual(['intro', 'guide'])
+  })
+
+  it('should find match by routeId pattern', () => {
+    const matches = createMatches()
+    const found = matches.find((m) => m.routeId.includes('_layout'))
+
+    expect(found).toBeDefined()
+    expect(found!.routeId).toBe('/_layout')
+  })
+
+  it('should get page match (last in array)', () => {
+    const matches = createMatches()
+    const pageMatch = matches[matches.length - 1]
+
+    expect(pageMatch.routeId).toBe('/docs/[slug]')
+    expect((pageMatch.loaderData as any).title).toBe('Introduction')
+  })
+
+  it('should get layout match for a page', () => {
+    const matches = createMatches()
+    // find the layout that contains "docs"
+    const layoutMatch = matches.find(
+      (m) => m.routeId.includes('/docs/') && m.routeId.includes('_layout')
+    )
+
+    expect(layoutMatch).toBeDefined()
+    expect((layoutMatch!.loaderData as any).navItems).toBeDefined()
+  })
+})

package/src/useMatches.ts

@@ -0,0 +1,125 @@
+import { useSyncExternalStore } from 'react'
+import { useServerContext } from './vite/one-server-only'
+import type { One } from './vite/types'
+
+/**
+ * Re-export for convenience
+ */
+export type RouteMatch = One.RouteMatch
+
+// client-side matches store for navigation updates
+let clientMatches: RouteMatch[] = []
+const clientMatchesListeners = new Set<() => void>()
+
+function subscribeToClientMatches(callback: () => void) {
+  clientMatchesListeners.add(callback)
+  return () => clientMatchesListeners.delete(callback)
+}
+
+function getClientMatchesSnapshot() {
+  return clientMatches
+}
+
+/**
+ * Update the client-side matches store.
+ * Called after navigation to update the matches with new loader data.
+ * @internal
+ */
+export function setClientMatches(matches: RouteMatch[]) {
+  clientMatches = matches
+  for (const listener of clientMatchesListeners) {
+    listener()
+  }
+}
+
+/**
+ * Returns an array of all matched routes from root to the current page.
+ * Each match contains the route's loader data, params, and route ID.
+ *
+ * On the server (SSR), this returns the matches computed during the request.
+ * On the client, this returns cached matches from hydration or the last navigation.
+ *
+ * @example
+ * ```tsx
+ * // In a layout component
+ * function DocsLayout({ children }) {
+ *   const matches = useMatches()
+ *   const pageMatch = matches[matches.length - 1]
+ *   const headings = pageMatch?.loaderData?.headings
+ *
+ *   return (
+ *     <div>
+ *       <TableOfContents headings={headings} />
+ *       {children}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Building breadcrumbs
+ * function Breadcrumbs() {
+ *   const matches = useMatches()
+ *
+ *   return (
+ *     <nav>
+ *       {matches.map((match) => (
+ *         <a key={match.routeId} href={match.pathname}>
+ *           {match.loaderData?.title ?? match.routeId}
+ *         </a>
+ *       ))}
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export function useMatches(): RouteMatch[] {
+  const serverContext = useServerContext()
+
+  // on server, return from context directly
+  if (process.env.VITE_ENVIRONMENT === 'ssr') {
+    return serverContext?.matches ?? []
+  }
+
+  // on client, use sync external store for reactivity
+  // the server snapshot (3rd arg) is used during hydration to match SSR output
+  const clientStoreMatches = useSyncExternalStore(
+    subscribeToClientMatches,
+    getClientMatchesSnapshot,
+    // server snapshot for hydration - must match what SSR rendered
+    () => serverContext?.matches ?? []
+  )
+
+  // always return client store on client - it's initialized from server context
+  // during hydration via initClientMatches, then updated on navigation
+  return clientStoreMatches
+}
+
+/**
+ * Find a specific match by route ID.
+ *
+ * @example
+ * ```tsx
+ * const docsMatch = useMatch('docs/_layout')
+ * const navItems = docsMatch?.loaderData?.navItems
+ * ```
+ */
+export function useMatch(routeId: string): RouteMatch | undefined {
+  const matches = useMatches()
+  return matches.find((m) => m.routeId === routeId)
+}
+
+/**
+ * Get the current page's match (the last/deepest match).
+ *
+ * @example
+ * ```tsx
+ * const pageMatch = usePageMatch()
+ * const { title, description } = pageMatch?.loaderData ?? {}
+ * ```
+ */
+export function usePageMatch(): RouteMatch | undefined {
+  const matches = useMatches()
+  return matches[matches.length - 1]
+}