自动集成 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 中最重要的部分之一是路由器，它负责导航和预取页面数据。此框架将为 next/router 和 next/navigation 模拟 Storybook 中所有必需的路由上下文。

next/navigation

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

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

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

Navigation 提供程序使用一些默认值进行配置。您可以通过设置 nextjs.navigation 的参数来覆盖这些默认值。

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

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

next/router

在 pages 目录中，您应继续为路由目的使用 next/router 的导入。如果您想配置 Router 提供程序，可以通过设置 nextjs.router 参数来完成。

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

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

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 结合使用。但我们可以做得更好。以下是我们未来计划的一瞥

让我们知道您使用此框架构建了什么，或者您还想使用哪些其他集成。在 @storybookjs 上发推文，或通过Storybook Discord 服务器联系我们！

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

特别感谢

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