[前端] 封装一下 echart 6，发布到 npm

文章目录

Npm
目标
准备工作
[库打包工具 Tsdown](#库打包工具 Tsdown)
库变动监听并打包
[Q：我的依赖包，和我的主项目，都需要安装 echarts 依赖吗？](#Q：我的依赖包，和我的主项目，都需要安装 echarts 依赖吗？)
封装库的步骤和一些思想
- 步骤
- 思想
[Demo 测试](#Demo 测试)
[npm 发包](#npm 发包)
[build 白屏的问题](#build 白屏的问题)

Npm

开发的包地址如下：https://www.npmjs.com/package/echarts-react-tools

目标

体验开发一个 npm 库的流程，包括开发，调试，发版等
在学习一下 echarts6

准备工作

在一个空的项目下，创建 packages 的文件夹，这个文件夹准备放我要开发的依赖项目

然后在项目根目录下，新建一个 pnpm-workspace.yaml 文件，用于搭建本地开发依赖库的说明。具体细节可以看 pnpm 的官网文档

https://pnpm.io/zh/workspaces

库打包工具 Tsdown

我选用的是 tsdown，这个是官方文档，也可以使用官网的开发模板快速搭建一个空项目 https://tsdown.dev/zh-CN/guide/getting-started

然后，编写一下配置文件，在项目根目录下写一个 tsdown.config.ts，注意要把

ts 复制代码

// tsdown.config.ts
import { defineConfig } from 'tsdown'

export default defineConfig({
    entry: ['./src/index.ts'],
    platform: 'neutral',
    dts: true,
    external: [
        'react',
        'react-dom',
        'echarts',
    ],
})

至于什么是 external，可以看下面的图

库变动监听并打包

开发库的话，每次都要 build 会比较烦，有 watch 的话，就会有类似前端的热更新。可以查看官方的文档

json 复制代码

 "scripts": {
    "build": "tsdown --watch",
    "test": "echo \"Error: no test specified\" && exit 1"
  },

可以看到热更新是好使的！这就方便了我们开发调试依赖库了。

Q：我的依赖包，和我的主项目，都需要安装 echarts 依赖吗？

peerDependencies 的真正含义（重点）

含义是：

"我需要 echarts，但我不负责安装，你用我，你就得给我 echarts"

这对「React 组件库 / hooks 库 / 工具库」来说是标准姿势。

React / Vue / Ant Design / React Router 全都是这么干的。

所以我接下来要注意的是

我的库，只能使用 echarts，不能拥有 echarts，同理 React 也是！

封装库的步骤和一些思想

步骤

1️⃣ 定义最佳使用方式（API 设计） ← 当前

2️⃣ 定义核心抽象（Chart / Option / Data）

3️⃣ 实现最小可用折线图

4️⃣ 抽象通用能力（resize / theme / loading）

5️⃣ 扩展到其他图表

6️⃣ 打磨文档 & 示例

思想

先定义"最佳使用方式（API 设计）" → 再倒推实现
"我的组件只是帮用户生成一个合理的默认 option，但最终 option 永远以用户为准"

我的想法是，这个库是 echarts 的增强版，也就是 任何时候，用户都可以退回到官方 ECharts 的思维方式

整体分层

json 复制代码

用户
  ↓
Chart 组件（LineChart）
  ↓
Option 工厂（useLineOption）
  ↓
Option 合并（mergeOption）
  ↓
ECharts Runtime（useBaseChart）
  ↓
echarts.setOption()

只写 props 的目的是：

这是一个刻意的工程步骤顺序

在库开发里，有三种"错误但常见"的节奏：

❌ 先写代码，再想 API

❌ 写着写着改架构

❌ 为了实现一个功能，破坏整体一致性

你现在做的是正确路径：

先冻结 API 和职责边界，再写实现

所以目前这三个模块是：

bash 复制代码

# 只在 echarts-react-tools 这个子包中安装依赖
pnpm add lodash.merge --filter echarts-react-tools

Demo 测试

我已经完成了折线图的定义，现在试一下

npm 发包

首先要去 npm 上获取一个 token

这个 token 只给你看一次，所以要复制到一个地方记一下

之后用 npm config 把你的 token 放到本地

bash 复制代码

// 1. 去 npm 官网上注册一个 token，然后写在自己电脑里
npm config set //registry.npmjs.org/:_authToken=*****你的 token*****

之后写一个发包的脚本

javascript 复制代码

#!/bin/bash
set -e

echo "🚀 准备发布 echarts-react-tools..."

# 检查 npm token 是否有效
if ! npm whoami > /dev/null 2>&1; then
  echo "❌ npm 未认证，请检查 ~/.npmrc 中的 authToken"
  exit 1
fi

# 检查 git 工作区
if [ -n "$(git status --porcelain)" ]; then
  echo "❌ 工作目录不干净，请先提交所有更改"
  exit 1
fi

# 版本升级
echo "🔢 请选择版本升级类型:"
select release in patch minor major; do
  npm version $release
  break
done

# 构建
echo "📦 构建项目..."
npm run build

# 检查包内容
echo "📋 npm pack 预览..."
npm pack --dry-run

# 发布
echo "📤 发布到 npm..."
npm publish --access public

echo "✅ 发布完成！"