Storybook for a Next.js app fails to build or shows broken stories
Module 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.
Fix it fast
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.*2Match what you see, then jump to its fix
- 1
package.json lists next below 14.1The Next.js version is older than the framework supportsFix - 2
Module not found: Error: Can't resolve 'css-loader' (or 'style-loader')Yarn 2 or 3 cannot resolve css-loader or style-loaderFix - 3
You are importing avif images, but you don't have sharp installed.An avif image is imported without sharp installedFix - 4
The story fails only when the component calls useRouter, usePathname or useParams from next/navigationComponents that use next/navigation need the appDirectory parameterFix - 5
The 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
An 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
- 1
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/navigationImages 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 next2Fix
Upgrade Next.js to a supported version before debugging anything else.
npm install next@latest react@latest react-dom@latest3Verify
Start Storybook again.
npm run storybookConfirmed by storybook.js.org
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 --version2Fix
Install the missing package directly as a dev dependency.
yarn add --dev css-loader style-loader3Verify
Run Storybook and confirm the module error is gone.
yarn storybookConfirmed by storybook.js.org
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=*.mdx2Fix
Install sharp, as the error says.
npm install sharp3Verify
Restart Storybook and open a story that shows the avif image.
npm run storybookConfirmed by storybook.js.org
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 components2Fix
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 preview3Verify
Reload the story that uses the hook.
npm run storybookConfirmed by storybook.js.org
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.tsx2Fix
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.tsx3Verify
Rebuild Storybook and open the new story.
npm run build-storybookConfirmed by storybook.js.org
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 components2Fix
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 storybookConfirmed by storybook.js.org
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
Web apps
"invariant expected app router to be mounted" in a Next.js app
Uncaught Error: invariant expected app router to be mounted
This error appears when a component calls useRouter imported from next/router while it renders inside the App Router.
3 causes, each with a fixWeb apps
AuthUserPoolException: Auth UserPool not configured in a Next.js app
Auth UserPool not configured
The error means an Amplify Auth call ran before Amplify.configure did.
3 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fix