自动集成 Next.js 和 Storybook

Next.js 被用于成千上万的网站和应用。随着 v13 的最新发布，它的能力比以往任何时候都更强大，包含了路由和图片优化等关键功能的许多改进。但随着所有这些变化，迁移现有的 Next 应用可能很困难，更不用说它集成的所有东西了。

Storybook 是独立组件开发的实际标准。我们很高兴通过我们新的 @storybook/nextjs 框架包在 Storybook 中提供 Next.js 13 功能。它会自动配置 Storybook 以镜像 Next.js 12 和 13 项目设置。以下是包含的内容：

🔀 路由
🖼 图片优化
⤵️ 绝对导入
🎨 样式
🎛 Webpack 和 Babel 配置
💫 还有更多！

等等，什么是框架？

Storybook 7 引入了框架 API，这是一种新的架构，它简化了集成，提高了性能，减小了安装大小，并且对许多流行的应用设置实现了零配置。

对于 Next.js 用户，框架 API 处理 React 渲染器、Webpack 构建器和项目设置的配置，因此您的 Storybook 行为就像您的应用一样。

让我们仔细看看这个框架提供的一些功能。

路由

Next.js 中最重要的部分之一是路由器，它处理页面数据的导航和预加载。这个框架将在您的 Storybook 中模拟所有必要的路由上下文，包括 next/router 和 next/navigation。

next/navigation

Next.js 13 引入了实验性的 app 目录，包含新功能和约定。它带来了嵌套路由和布局的支持。

如果您的故事使用了 app 目录中的组件，并且它们从 next/navigation 导入模块，您必须通过将 nextjs.appDirectory 参数设置为 true 来告诉 Storybook 使用正确的模拟路由器上下文

export const Example = {
  parameters: {
    nextjs: {
      appDirectory: true,
    },
  },
};

导航提供程序配置了一些默认值。您可以通过设置 nextjs.navigation 的参数来覆盖这些默认值

export const Example = {
  parameters: {
    nextjs: {
      appDirectory: true,
      navigation: {
        pathname: '/profile,
        query: {
          user: 'santa',
        },
      },
    },
  },
};

查看AppRouterProvider 以了解所有可用参数。

next/router

在 pages 目录中，您应该继续使用从 next/router 导入的内容进行路由。如果您想配置路由器提供程序，可以通过设置 nextjs.router 参数来实现

export const Example = {
  parameters: {
    nextjs: {
      router: {
        basePath: '/profile',
      },
    }
  },
};

查看PageRouterProvider 以了解所有可用参数。

Actions

此框架还会自动将actions应用于模拟路由器的 方法。当您在故事中点击链接时，该方法会记录在 Actions 插件面板中。甚至当链接被悬停时，它也会记录预加载事件。

图片优化

Next.js 通过 next/image 组件包含复杂的图片优化。这个框架模拟了该组件的实现，使得 Next.js 和 Storybook 都能按预期工作，无需更改您的代码。

如果您使用 Next.js 12 搭配 next/future/image 或 Next.js 13 搭配 next/legacy/image，这些也完全支持。

绝对导入

为 Next.js 应用编写组件时，您可以在导入其他模块时使用绝对引用。这个框架确保当组件在 Storybook 中渲染时也能正常工作。这意味着以下代码在 Next.js 和 Storybook 中将以相同的方式工作

// pages/index.jsx
 
// Note that the import is not from '../components/Button'
import Button from 'components/button';
import styles from 'styles/HomePage.module.css';
 
export default function HomePage() {
  return (
    <>
      <h1 className={styles.title}>Hello World</h1>
      <Button />
    </>
  );
}

它在 preview.js 中也有效

// .storybook/preview.js
import 'styles/globals.scss';
 
// ...

样式

Sass、CSS Modules 和 Styled JSX 都是 Next.js 中可用的样式选项，并且这个框架支持所有这些选项。它甚至尊重在 next.config.js 中提供的自定义 Sass 配置。

// next.config.js
const path = require('path');
 
module.exports = {
  // any options here are included in sass compilation for your stories
  sassOptions: {
    includePaths: [path.join(__dirname, 'styles')],
  },
};

Webpack 和 Babel 配置

Next.js 拥有一个强大、复杂且隐藏的 Webpack 配置，它支持上述功能以及更多。这个框架为 Storybook 重建了该配置。更重要的是，它尊重您对该配置所做的任何扩展，因此您的应用在 Storybook 的独立开发环境中将按预期工作。

从 v12 开始，Next.js（可选地）使用 SWC 而不是 Babel 来处理越来越多的构建和开发过程。Storybook 尚不支持 SWC，因此此框架选择使用 Babel（仅限 Storybook）。

如果您的 Next.js 应用通过使用自己的 Babel 配置选择退出 SWC，那么此框架将尊重该自定义配置。但是，如果您正在使用自定义 SWC 配置，则需要将该行为转换为 Babel 并直接提供给 Storybook。我们正在研究如何更直接地支持 SWC。

开始使用

@storybook/nextjs 框架支持 Storybook 7（目前处于测试阶段）和 Next.js 12+。

您可以查看完整文档。开始使用非常简单。

新项目

使用单个命令添加预配置了此框架的 Storybook

npx storybook init

该命令将自动检测您的 Next.js 项目，然后安装和配置此框架及其他 Storybook 包。它看起来像这样

现有项目

如果您已经在使用 Storybook，请使用此命令升级 Storybook 并添加此预配置框架

npx storybook upgrade

这将执行以下操作

1. 将您的项目升级到最新版本的 Storybook
2. 建议与该升级相关的自动迁移
3. 其中一项自动迁移将安装并配置此框架

如果自动迁移不适用于您的项目，请参阅手动迁移说明。

就是这样！您现在可以在 Storybook 中开发、测试和文档化您的 Next.js 应用组件了。

更多内容即将到来

使用 @storybook/nextjs 框架，Storybook 和 Next.js 的结合比以往任何时候都更容易。但我们可以做得更好。以下是我们的未来计划预览

告诉我们您使用此框架构建了什么，或者您希望使用哪些其他集成。可以在 Twitter 上发送推文给@storybookjs 或通过Storybook Discord 服务器与我们联系！

如果您想编写自己的框架，我们有全新的指南来帮助您。

特别鸣谢

此框架的代码和功能基于 Ryan Clements 的 storybook-addon-next 和 Aaron Reisman 的 storybook-addon-next-router。感谢他们为我们提供了坚实的基础。我们还收到了来自 Vercel 朋友们的宝贵反馈和指导。