React Cosmos 与 Next.js 集成指南：实现服务端与客户端组件开发-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00581/article/details/148440450

React Cosmos 与 Next.js 集成指南：实现服务端与客户端组件开发

react-cosmos Sandbox for developing and testing UI components in isolation 项目地址: https://gitcode.com/gh_mirrors/re/react-cosmos

前言

在现代前端开发中，组件化开发已经成为主流趋势。React Cosmos 作为一个强大的组件开发环境，能够帮助开发者独立构建、测试和迭代 React 组件。而 Next.js 作为流行的 React 框架，其最新版本（13.4+）引入了革命性的 React 服务端组件（RSC）功能。本文将详细介绍如何将 React Cosmos 与 Next.js 深度集成，实现服务端与客户端组件的无缝开发体验。

环境准备

1. 创建或准备 Next.js 项目

首先确保你有一个 Next.js 13.4+ 的项目。如果还没有，可以通过官方脚手架工具创建一个新项目。

2. 安装必要依赖

在项目中安装 React Cosmos 及其 Next.js 适配器：

npm install -D react-cosmos react-cosmos-next

这两个包将提供开发环境和 Next.js 集成所需的所有功能。

配置 React Cosmos

1. 创建配置文件

在项目根目录下创建 cosmos.config.json 文件，配置渲染器 URL：

{
  "rendererUrl": {
    "dev": "http://localhost:3000/cosmos/<fixture>",
    "export": "/cosmos/<fixture>.html"
  }
}

这个配置告诉 Cosmos 如何连接到你的 Next.js 渲染器。

2. 添加脚本命令

在 package.json 中添加以下脚本：

"scripts": {
  "cosmos": "cosmos --expose-imports",
  "cosmos-export": "cosmos-export --expose-imports"
}

--expose-imports 标志会生成一个包含所有 fixture 导入的特殊文件。

创建第一个 Fixture

1. 基本组件示例

在 src 目录下创建一个简单的 fixture 文件 Hello.fixture.jsx：

export default <h1>Hello World!</h1>;

对于 TypeScript 项目，请使用 .tsx 扩展名。

2. 创建 Cosmos 渲染器

Next.js 的特殊之处在于需要一个专门的页面来渲染 Cosmos 组件。在 src/app/cosmos/[fixture]/page.tsx 创建以下内容：

import { nextCosmosPage, nextCosmosStaticParams } from 'react-cosmos-next';
import * as cosmosImports from '../../../../cosmos.imports';

export const generateStaticParams = nextCosmosStaticParams(cosmosImports);

export default nextCosmosPage(cosmosImports);

这个页面将作为 Cosmos 组件的渲染入口。

启动开发环境

1. 启动 Next.js 开发服务器

npm run dev

2. 启动 React Cosmos（在另一个终端）

npm run cosmos

启动后，你会注意到生成了一个 cosmos.imports.js 文件。这个文件由 Cosmos 服务器自动维护，包含了所有 fixture 的导入信息，可以将其添加到 .gitignore 中。

访问 localhost:5000 即可看到 React Cosmos 界面，现在你可以开发服务端组件了！

服务端与客户端组件

1. 混合开发模式

在 fixture 中，你可以自由导入服务端和客户端组件。默认情况下，组件会在服务端渲染。如果需要使用 React Hooks，只需在 fixture 模块顶部添加 'use client' 指令。

2. 注意事项

只有组件 Fixture 可以在使用 'use client' 的模块中导出
节点 Fixture 和 多 Fixture 不能在客户端 fixture 中使用
所有 Cosmos fixture 格式在服务端 fixture 中都受支持

静态导出部署

要创建静态版本的 Cosmos 环境，需要执行以下步骤：

# 构建 Cosmos
npm run cosmos-export
# 构建 Next.js
npm run build
# 将 Next.js 构建结果复制到 Cosmos 导出目录
cp -R ./out/_next ./cosmos-export
cp -R ./out/cosmos ./cosmos-export

完成后，可以使用任何静态文件服务器（如 http-server）来提供导出内容：