Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Storybook for a Next.js app fails to build or shows broken stories

ErrorModule not found: Error: Can't resolve 'css-loader'

Short answer

Storybook's Next.js framework needs Next.js 14.1 or newer, and each failure has its own documented fix. Install css-loader and style-loader under Yarn 2 or 3, install sharp for avif images, set the nextjs appDirectory parameter for next/navigation hooks, and keep Node-only page code out of stories.

  • Applies to Storybook Next.js framework, Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the first error line Storybook prints, then check the Next.js version and the framework package it is configured with. The error text maps straight to one cause below.

    npm ls next @storybook/nextjs @storybook/nextjs-vite
    grep -n "framework" .storybook/main.*
  2. 2Match what you see, then jump to its fix

    1. 1package.json lists next below 14.1The Next.js version is older than the framework supportsFix
    2. 2Module not found: Error: Can't resolve 'css-loader' (or 'style-loader')Yarn 2 or 3 cannot resolve css-loader or style-loaderFix
    3. 3You are importing avif images, but you don't have sharp installed.An avif image is imported without sharp installedFix
    4. 4The story fails only when the component calls useRouter, usePathname or useParams from next/navigationComponents that use next/navigation need the appDirectory parameterFix
    5. 5The Storybook build crashes after you add a story for a whole page fileA story imports a page that fetches data with Node-only modulesFix
    6. 6An img tag or a style that expects a string gets an object, and the image does not showA static image import is an object, not a path stringFix

What does the error look like?

  • Module not found: Error: Can't resolve 'css-loader'
  • Module not found: Error: Can't resolve 'style-loader'
  • You are importing avif images, but you don't have sharp installed.
  • A component that works in the app fails in Storybook when it calls useRouter, usePathname or useParams from next/navigation
  • Images imported into a story do not display

Cause 1 of 6

The Next.js version is older than the framework supports

1Check

The Storybook docs list Next.js 14.1 or newer as the requirement for the Next.js framework. The npm ls output in the first step shows the installed version.

npm ls next

2Fix

Upgrade Next.js to a supported version before debugging anything else.

npm install next@latest react@latest react-dom@latest

3Verify

Start Storybook again.

npm run storybook

Confirmed by storybook.js.org

Did this fix it?

Cause 2 of 6

Yarn 2 or 3 cannot resolve css-loader or style-loader

1Check

The Storybook docs have a note for Yarn v2 and v3 users: Storybook may not be able to resolve these two loaders. Check which Yarn version the project uses.

yarn --version

2Fix

Install the missing package directly as a dev dependency.

yarn add --dev css-loader style-loader

3Verify

Run Storybook and confirm the module error is gone.

yarn storybook

Confirmed by storybook.js.org

Did this fix it?

Cause 3 of 6

An avif image is imported without sharp installed

1Check

Look for .avif files imported by components or stories.

grep -rn "\.avif" src app components --include=*.tsx --include=*.ts --include=*.mdx

2Fix

Install sharp, as the error says.

npm install sharp

3Verify

Restart Storybook and open a story that shows the avif image.

npm run storybook

Confirmed by storybook.js.org

Did this fix it?

Cause 4 of 6

Components that use next/navigation need the appDirectory parameter

1Check

In the Next.js framework, next/router is stubbed and meant for the pages directory. A component that uses next/navigation needs the nextjs.appDirectory parameter.

grep -rln "next/navigation" src app components

2Fix

Set the parameter for the whole project in .storybook/preview, or on a single story or component. Use the framework package name your project has.

// .storybook/preview.tsx
// use '@storybook/nextjs-vite' here if that is your framework package
import type { Preview } from '@storybook/nextjs'

const preview: Preview = {
  parameters: {
    nextjs: {
      appDirectory: true,
    },
  },
}

export default preview

3Verify

Reload the story that uses the hook.

npm run storybook

Confirmed by storybook.js.org

Did this fix it?

Cause 5 of 6

A story imports a page that fetches data with Node-only modules

1Check

The Storybook docs say a page file importing Node.js-only modules does not work in Storybook, because the browser cannot run those modules.

grep -n "^import" app/products/page.tsx

2Fix

Move the visual part of the page into its own file and write the story against that component, as the Storybook docs recommend.

// app/products/ProductList.tsx  (pure component, props only)
export function ProductList({ items }: { items: { id: string; name: string }[] }) {
  return <ul>{items.map((i) => <li key={i.id}>{i.name}</li>)}</ul>
}

// ProductList.stories.tsx imports ProductList, not page.tsx

3Verify

Rebuild Storybook and open the new story.

npm run build-storybook

Confirmed by storybook.js.org

Did this fix it?

Cause 6 of 6

A static image import is an object, not a path string

1Check

The Storybook docs say an imported image now arrives as an object, with src, height, width and blurDataURL, instead of only the path.

grep -rn "import .* from .*\.\(png\|jpg\|svg\)" src components

2Fix

Use the object's src where a plain path is needed, or pass the object to next/image.

import logo from './logo.png'

// <img src={logo.src} alt="" />
// <Image src={logo} alt="" />

3Verify

Open the story and confirm the image loads.

npm run storybook

Confirmed by storybook.js.org

Did this fix it?

How do I stop it coming back?

  • Pick the framework package on purpose: Storybook's Next.js docs recommend the Vite one for most projects and the webpack one when you need custom webpack or Babel config.
  • Keep Node-only code (database clients, fs) in files that stories never import, and keep pure components separate from data fetching.
  • Set the appDirectory parameter once in preview instead of story by story.
  • Run the Storybook build in CI so a broken import fails a pull request.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.