This recipe assumes that you are using Next.js >= 12.x as well as Storybook >= 7.x
How to setup Next.js and Storybook
Tens of thousands of websites and apps rely on Next.js for its powerful features, and the latest release of version 13 has brought many improvements, particularly in routing and image optimization. However, transitioning your existing Next app, along with its integrations, can be a daunting task.
Fortunately, there is now an easier way to develop isolated components with the new @storybook/nextjs framework package. As an industry-standard for component development, Storybook is proud to offer Next.js 13 features in a seamless integration. With our package, Storybook automatically mirrors the project settings of both Next.js 12 and 13. Here's what you'll get:
- 🔀 Routing
- 🖼 Image optimization
- ⤵️ Absolute imports
- 🎨 Styling
- 🎛 Webpack & Babel config
- 💫 and more!
In a project without Storybook
Follow the prompts after running this command in your Next.js project's root directory:
In a project with Storybook
This framework is designed to work with Storybook 7. If you’re not already using v7, upgrade with this command:
Automatic migration
When running the upgrade command above, you should get a prompt asking you to migrate to @storybook/nextjs, which should handle everything for you. In case that auto-migration does not work for your project, refer to the manual migration below.
Manual migration
Install the framework:
Update your main.js to change the framework property:
If you were using Storybook plugins to integrate with Next.js, those are no longer necessary when using this framework and can be removed:
Configuring next/navigation
Next.js 13 introduced the experimental app directory with new features and conventions. It brings support for nested routes and layouts.
If your story uses components in the app directory and they are importing modules from next/navigation, you have to tell Storybook to use the correct mocked router context by setting the nextjs.appDirectory parameter to true:
The Navigation provider is configured with some defaults. You can override those defaults by setting the parameter for nextjs.navigation:
Take a look at the AppRouterProvider for all available parameters.
Configuring next/router
Within the pages directory, you should continue to use imports from next/router for routing purposes. If you want to configure the Router provider, you can do so by setting the nextjs.router parameter:
Take a look at the PageRouterProvider for all available parameters.
Get involved
Now you're ready to use Next.js with Storybook. 🎉 If you use Nextjs at work, we'd love your feedback on the Next + Storybook experience.
Join the maintainers and our thriving community in Discord.