feat: adds nextjs parallel routs support

Author: feugy

apps/nextjs/app/blog/page.tsx

@@ -5,6 +5,7 @@ export default function Blog() {
     <div>
       <h1>Welcome to the Blog</h1>
       <Link href="/blog/test">First blog entry</Link>
+      <Link href="/parallel-routes/dashboard">Parallel routes (App Router)</Link>git 
     </div>
   );
 }

apps/nextjs/app/parallel-routes/@sidebar/[...catchAll]/page.tsx

@@ -0,0 +1,37 @@
+import { computeRoute } from '@vercel/speed-insights';
+import Link from 'next/link';
+
+export default async function SidebarCatchAll({ params }: { params: Promise<{ catchAll: string[] }> }) {
+  const { catchAll } = await params;
+  const path = `/parallel-routes/${catchAll.join('/')}`;
+  const route = computeRoute(path, { catchAll });
+
+  return (
+    <div
+      style={{
+        padding: '1rem',
+        backgroundColor: '#fff3e0',
+        border: '2px dashed orange',
+        marginTop: '1rem',
+      }}
+    >
+      <h3 style={{ marginBottom: '1rem' }}>@sidebar Slot (Parallel Route)</h3>
+      <p>
+        <strong>catchAll param:</strong> [{catchAll?.join(', ')}]
+      </p>
+      <p>
+        <strong>Computed route:</strong> {route}
+      </p>
+
+      <h3 style={{ marginTop: '1rem' }}>Test Routes:</h3>
+      <ul style={{ padding: '1rem 0 0 1rem' }}>
+        <li>
+          <Link href="/parallel-routes/dashboard">Dashboard (static)</Link>
+        </li>
+        <li>
+          <Link href="/parallel-routes/settings">Settings (static)</Link>
+        </li>
+      </ul>
+    </div>
+  );
+}

apps/nextjs/app/parallel-routes/@sidebar/default.tsx

@@ -0,0 +1,7 @@
+export default function SidebarDefault() {
+  return (
+    <div style={{ padding: '1rem', backgroundColor: '#f5f5f5' }}>
+      <p>@sidebar default (no active parallel route)</p>
+    </div>
+  );
+}

apps/nextjs/app/parallel-routes/dashboard/page.tsx

@@ -0,0 +1,34 @@
+import { computeRoute } from '@vercel/speed-insights';
+
+export default function DashboardPage() {
+  const path = '/parallel-routes/dashboard';
+  const route = computeRoute(path, {});
+
+  return (
+    <div style={{ padding: '2rem' }}>
+      <h1>Dashboard (Static Route)</h1>
+      <p>This is a static page with no dynamic params.</p>
+
+      <div
+        style={{
+          marginTop: '1rem',
+          padding: '1rem',
+          backgroundColor: '#e3f2fd',
+        }}
+      >
+        <p>
+          <strong>Path:</strong> {path}
+        </p>
+        <p>
+          <strong>Computed route:</strong> {route}
+        </p>
+      </div>
+
+      <p style={{ marginTop: '1rem', color: '#666' }}>
+        The sidebar slot (<code>@sidebar/[...catchAll]</code>) matches this path with{' '}
+        <code>catchAll: [&apos;dashboard&apos;]</code>. The <code>Analytics</code> component in the root layout sees
+        both sets of params via <code>useParams()</code>, causing it to compute the wrong route.
+      </p>
+    </div>
+  );
+}

apps/nextjs/app/parallel-routes/layout.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+
+export default function ParallelRoutesLayout({ children, sidebar }: { children: ReactNode; sidebar: ReactNode }) {
+  return (
+    <div style={{ padding: '1rem' }}>
+      <div style={{ display: 'grid', gridTemplateColumns: '1fr 2fr', gap: '1rem' }}>
+        <aside>{sidebar}</aside>
+        <main>{children}</main>
+      </div>
+    </div>
+  );
+}

apps/nextjs/app/parallel-routes/settings/page.tsx

@@ -0,0 +1,28 @@
+import { computeRoute } from '@vercel/speed-insights';
+
+export default function SettingsPage() {
+  const path = '/parallel-routes/settings';
+  const route = computeRoute(path, {});
+
+  return (
+    <div style={{ padding: '2rem' }}>
+      <h1>Settings (Static Route)</h1>
+      <p>This is a static page with no dynamic params.</p>
+
+      <div
+        style={{
+          marginTop: '1rem',
+          padding: '1rem',
+          backgroundColor: '#e3f2fd',
+        }}
+      >
+        <p>
+          <strong>Path:</strong> {path}
+        </p>
+        <p>
+          <strong>Computed route:</strong> {route}
+        </p>
+      </div>
+    </div>
+  );
+}

packages/web/src/nextjs/utils.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from 'vitest';
-import { getBasePath, getConfigString } from './utils';
+import { filterParallelRouteParams, getBasePath, getConfigString } from './utils';
 
 const processSave = { ...process };
 const envSave = { ...process.env };
@@ -9,6 +9,49 @@ afterEach(() => {
   process.env = { ...envSave };
 });
 
+describe('filterParallelRouteParams()', () => {
+  it('filters single-segment slot catch-all from static main route', () => {
+    // @sidebar/[...catchAll] matched "dashboard" — a single segment not in main route
+    const result = filterParallelRouteParams(
+      { catchAll: ['dashboard'] },
+      ['dashboard'],
+    );
+    expect(result).toEqual({});
+  });
+
+  it('keeps multi-segment catch-all that appears in segments', () => {
+    const result = filterParallelRouteParams(
+      { slug: ['blog', 'my-post'] },
+      ['blog/my-post'],
+    );
+    expect(result).toEqual({ slug: ['blog', 'my-post'] });
+  });
+
+  it('keeps string params and filters slot array params', () => {
+    const result = filterParallelRouteParams(
+      { id: 'abc', catchAll: ['dashboard'] },
+      ['some-other-segment'],
+    );
+    expect(result).toEqual({ id: 'abc' });
+  });
+
+  it('filters multi-segment slot catch-all whose joined value is not in segments', () => {
+    const result = filterParallelRouteParams(
+      { catchAll: ['a', 'b'] },
+      ['c', 'd'],
+    );
+    expect(result).toEqual({});
+  });
+
+  it('keeps all params when segments is empty', () => {
+    const result = filterParallelRouteParams(
+      { id: 'abc', slug: ['x', 'y'] },
+      [],
+    );
+    expect(result).toEqual({ id: 'abc' });
+  });
+});
+
 describe('getBasePath()', () => {
   it('returns null without process', () => {
     // @ts-expect-error -- yes, we want to completely drop process for this test!!

packages/web/src/nextjs/utils.ts

@@ -1,5 +1,10 @@
 'use client';
-import { useParams, usePathname, useSearchParams } from 'next/navigation.js';
+import {
+  useParams,
+  usePathname,
+  useSearchParams,
+  useSelectedLayoutSegments,
+} from 'next/navigation.js';
 import { computeRoute } from '../utils';
 
 export const useRoute = (): string | null => {
@@ -10,13 +15,32 @@ export const useRoute = (): string | null => {
   if (!params) {
     return null;
   }
+  const segments = useSelectedLayoutSegments();
   // in Next.js@13, useParams() could return an empty object for pages router, and we default to searchParams.
-  const finalParams = Object.keys(params).length
+  const paramObject = Object.keys(params).length
     ? params
     : Object.fromEntries(searchParams.entries());
+
+  const finalParams =
+    segments !== null
+      ? filterParallelRouteParams(paramObject, segments)
+      : paramObject;
   return computeRoute(path, finalParams);
 };
 
+export function filterParallelRouteParams(
+  params: Record<string, string | string[]>,
+  segments: string[],
+): Record<string, string | string[]> {
+  return Object.fromEntries(
+    Object.entries(params).filter(([, value]) => {
+      if (!Array.isArray(value)) return true;
+      const joined = value.join('/');
+      return joined.includes('/') && segments.includes(joined);
+    }),
+  );
+}
+
 // !! important !!
 // do not access env variables using process.env[varname]
 // some bundlers won't replace the value at build time.