Core: Support array-based catch-all Next.js route segments in AppRouterProvider

[yatishgoel]

Closes #31523

What I did

This PR fixes an issue where the Next.js framework addon (for both Webpack and Vite) did not correctly handle array values for route parameters when using the App Router (appDirectory: true). Specifically, components using useParams() for catch-all or optional catch-all routes (e.g., [[...slug]] or [...slug]) would not receive the parameter as an array if specified as such in the story's parameters.nextjs.navigation.segments.

The AppRouterProvider has been updated to:

• Directly process parameters.nextjs.navigation.segments to construct the pathParams object provided to PathParamsContext.
• Support segments defined as an array of [key, value] tuples (e.g., [['directories', ['a', 'b']]]).
• Support segments defined as an object (e.g., { directories: ['a', 'b'] }), enhancing flexibility.
• Ensure that if a value for a parameter is an array, it is preserved as an array, allowing useParams() to receive it correctly.

The getSelectedParams utility function was also made more robust to handle cases where a segment value within the FlightRouterState might already be an array, preventing potential runtime errors.

This change enables stories to accurately mock and test components that rely on array-based route parameters from Next.js's dynamic routing.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

1. Generate a Next.js sandbox

   cd storybook
   yarn task --task sandbox --template nextjs/default-ts

2. Start the sandbox in development mode

   cd sandbox/nextjs-default-ts
   yarn task --task dev --template nextjs/default-ts --start-from=install
   # or
   yarn storybook dev -p 6006

3. Add a test component
   Create src/components/TestComponent.tsx inside the sandbox:

   'use client';
   import { useParams } from 'next/navigation';
   
   export function TestComponent() {
     const { items } = useParams<{ items?: string[] }>();
     return <div data-testid="items">{JSON.stringify(items || [])}</div>;
   }

4. Add a corresponding story
   Create src/stories/TestComponent.stories.tsx:

   import type { Meta, StoryObj } from '@storybook/react';
   import { TestComponent } from '../components/TestComponent';
   
   const meta: Meta<typeof TestComponent> = {
     component: TestComponent,
     title: 'Sandbox/TestComponent',
     parameters: {
       nextjs: {
         appDirectory: true,
         navigation: {
           segments: [['items', ['one','two','three']]],
           pathname: '/test/one/two/three',
         },
       },
     },
   };
   export default meta;
   type Story = StoryObj<typeof TestComponent>;
   
   export const WithItems: Story = {};

5. Verify in Storybook

   • Open the Sandbox → TestComponent story.
   • Confirm the <div data-testid="items"> renders ["one","two","three"].
   • Ensure no console errors occur and the parameter remains a string array.

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

Greptile Summary

Enhanced AppRouterProvider to properly handle array-based catch-all route segments in Next.js, ensuring correct parameter handling for dynamic routes like [...slug] and [[...slug]].

• Modified getSelectedParams in code/frameworks/nextjs/src/routing/app-router-provider.tsx to handle pre-existing array segment values
• Updated pathParams generation to support both array tuples ([['key', ['value1', 'value2']]]) and object format segments
• Added support for catch-all route parameters in useParams() hook responses
• Synchronized changes between Next.js and Next.js-Vite framework implementations
• Maintained backward compatibility while fixing array parameter handling for App Router

[greptile-apps]

_{2 file(s) reviewed, 2 comment(s)
Edit PR Review Bot Settings | Greptile}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 3ef9c74.

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	1m 11s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-06-16 08:46:27 UTC

[valentinpalkovic]

Hi @yatishgoel,

Thank you for your PR! Much appreciated!

Could you please add some stories in code/frameworks/nextjs/template/stories/Navigation.stories.tsx and code/frameworks/nextjs-vite/template/stories/Navigation.stories.tsx so that we can easily verify its functionality?