Storybook 10 -> Next JS 16.0.3 -> Vitest Conflicts

[chrisbeldam]

Summary

I've recently joined a team which is using Next 16.0.3. I've upgraded to Storybook 10.0.8 to allow for Storybook to load again.

Our codebase is using the following mocks

  storybookNavigationMock: fromRoot(
    "node_modules/@storybook/nextjs/dist/export-mocks/navigation/index.js",
  ),
  storybookRouterMock: fromRoot(
    "node_modules/@storybook/nextjs/dist/export-mocks/router/index.js",
  ),

However when running our Vitest Suite we get the following error:

Error: Cannot find module '/Users/christopherbeldam/Code/eb-sherloc-web-app/node_modules/next/dist/client/components/navigation' imported from /Users/christopherbeldam/Code/eb-sherloc-web-app/node_modules/@storybook/nextjs/dist/export-mocks/navigation/index.js Did you mean to import "next/dist/client/components/navigation.js"?

It looks like Storybook is looking for a file without the .js extension which does not exist anymore in NextJS from what i can see.

Is there a way to fix this? Temporarily mock these functions etc?

Additional information

No response

Create a reproduction

No response

[dosubot[bot]]

Hi @chrisbeldam! I'm Dosu and I’m helping the storybook team.

The error is happening because Storybook's Next.js navigation mock imports from a deep internal Next.js path without the .js extension, but Next.js 16.x now requires explicit extensions for module resolution. This breaks Vitest when running tests.

Here’s how you can work around it:

• Switch to official Storybook mock entry points: Instead of importing directly from @storybook/nextjs/dist/export-mocks/navigation/index.js, use @storybook/nextjs/navigation.mock and @storybook/nextjs/router.mock in your code and test config. These are designed to be portable and avoid deep internal imports.

• Configure Vitest aliases: In your vitest.config.ts, use the resolve.alias option to redirect imports like 'next/navigation' to '@storybook/nextjs/navigation.mock'. Storybook provides a helper (getPackageAliases from @storybook/nextjs/export-mocks) to generate these mappings.
  Example:

  import { getPackageAliases } from '@storybook/nextjs/export-mocks';
  
  export default defineConfig({
    resolve: {
      alias: {
        ...getPackageAliases(),
      },
    },
    // ...other config
  });

  Reference

• If you still hit deep import errors: Create a custom mock file at __mocks__/next/dist/client/components/navigation.js in your project root. Export the same named exports as the original module. Vitest and Storybook will pick this up automatically for deep imports.
  How to set up mocks

• Register mocks in Storybook: Use sb.mock() in .storybook/preview.js|ts to ensure Storybook uses your mocks globally.

• Consider using the experimental Next.js Vite framework: If you’re not already, switching your Storybook config to use @storybook/experimental-nextjs-vite can improve compatibility with Next.js 16 and Vite/Vitest.
  Framework info

Keep in mind: If you create custom mocks for deep internals, you’ll need to keep them in sync with any Next.js API changes. Watch for updates from Storybook and Next.js for upstream fixes.

If you need more help, please share a minimal reproduction or your current Vitest config.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[chrisbeldam]

@dosu I am afraid this did not work

[dosubot[bot]]

Let's troubleshoot why the manual mock isn't working:

1. What is the exact error message you see after adding the mock? Is it still "module not found," or something else?

2. Can you confirm the mock file is at:
   __mocks__/next/dist/client/components/is-next-router-error.js
   and contains something like:

   export function isNextRouterError() {
     return false;
   }

   (It must be plain JavaScript, not TypeScript, and use ESM export.)

3. Is your project root (where __mocks__ lives) the same as your Vite root? If not, try moving __mocks__ to the directory containing .storybook.

4. Does your package.json have "type": "module" and your tsconfig.json use "moduleResolution": "bundler"?

5. Try clearing Vite's cache and restarting the dev server/test runner—sometimes new mocks aren't picked up until then.

6. If the above doesn't help, try explicitly mocking in your test setup file:

   vi.mock('next/dist/client/components/is-next-router-error', () => ({
     isNextRouterError: () => false,
   }));

Let me know the answers to the above, or paste the error message you see now. That will help pinpoint the next step.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[chrisbeldam]

@dosu This worked but reproduced the same error for node_modules/next/dist/client/head-manager

[chrisbeldam]

@dosu Any ideas on how to resolve these next clashes?

[dosubot[bot]]

These clashes happen because Storybook and Vitest don’t provide built-in mocks for deep Next.js internals like next/dist/client/head-manager, so you need to manually mock them.

Here’s what works best for these cases:

• Create a mocks directory at your project root (same level as package.json).
• Inside mocks, replicate the folder structure of the module you want to mock. For example, for head-manager, create mocks/next/dist/client/head-manager.js.
• In that file, export the same named exports as the real module, using ESM syntax (not CommonJS). For example:

  // __mocks__/next/dist/client/head-manager.js
  export default function initHeadManager() {
    // Return a minimal mock object as needed by your code
    return {
      updateHead: () => {},
      mountedInstances: new Set(),
      updateScripts: () => {},
      scripts: [],
      getIsSsr: () => false,
    };
  }

• If the module has named exports, export them as well.

If the mock isn’t picked up, try:

• Restarting the dev server and clearing Vite’s cache.
• Ensuring your project uses "type": "module" in package.json and "moduleResolution": "bundler" in tsconfig.json.
• As a fallback, add an explicit vi.mock() call in your Vitest setup file:

  vi.mock('next/dist/client/head-manager', () => ({
    default: () => ({
      updateHead: () => {},
      mountedInstances: new Set(),
      updateScripts: () => {},
      scripts: [],
      getIsSsr: () => false,
    }),
  }));

For future clashes, repeat this process for any deep Next.js internal import that causes errors. If you want to avoid manual mocks, you can also look into subpath imports in package.json or builder aliases, but manual mocks are the most direct fix for these deep internals right now.
More details and examples: Storybook module mocking docs
Background on why this is needed: Storybook blog on next-gen module mocking

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}