自动集成 Next.js 和 Storybook

Next.js 被成千上万的网站和应用程序使用。随着最近 v13 的发布，它比以往任何时候都更加强大，包括对路由和图像优化等关键功能的许多改进。但是，随着所有这些变化，迁移现有的 Next 应用程序可能很困难，更不用说它集成的所有内容了。

Storybook 是隔离组件开发的 фактический 标准。我们很高兴通过我们新的 @storybook/nextjs 框架包，使 Next.js 13 的功能在 Storybook 中可用。它自动配置 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 目录，其中包含新功能和约定。它带来了对嵌套路由和布局的支持。

如果您的 story 使用 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 以获取所有可用参数。

操作

此框架还自动将操作应用于模拟路由器的函数。当您单击 story 中的链接时，该函数将记录在 Actions 插件面板中。它甚至会在悬停链接时记录预取事件。

图像优化

Next.js 通过 next/image 组件包含复杂的图像优化。此框架模拟此组件的实现，这使 Next.js 和 Storybook 都可以按预期工作，而无需更改您的代码。

如果您使用带有 next/future/image 的 Next.js 12 或带有 next/legacy/image 的 Next.js 13，它们也完全受支持。

绝对导入

在为 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（目前为 beta 版）和 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 服务器上联系我们！

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

特别感谢

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