使用 ICE PKG 开发并发布支持多场景引用的 NPM 包

前言

在开发中，我们经常需要将功能模块封装为 npm 包以便复用。

本文将介绍如何使用 ICE PKG 开发一个同时支持 npm 安装和浏览器 umd 引用的组件包。

什么是 ICE PKG？

ICE PKG 是飞冰开源的 NPM 包开发解决方案，默认支持 React 组件、Rax 组件、Node 模块、前端类库等多场景 NPM 包的研发。

为什么选择 ICE PKG？

📈 更快：使用 SWC 编译和压缩，提升数十倍编译速度
🎊 双模式：同时提供 Transform + Bundle 两种构建模式
🅾️ 零配置：无需任何配置，提供内建的 TypeScript、JSX 等构建支持
☄️ 面向未来：提供 ES2017 产物，打包出面向现代浏览器支持的产物
☘️ 文档预览 ：基于 Docusaurus 提供预览文档、生成静态文档能力

接下来话不多说直接开始吧!

快速开始

大家也可以直接参考官方文档：pkg.ice.work/quick-start

环境准备

1. Node.js

使用 ICE PKG 开发前需要安装 Node.js，并确保 node 版本是 16.14 或以上。

2. 包管理工具

安装 Node.js 后，默认会包含 npm。在国内使用 npm 安装依赖可能会比较慢。建议使用 cnpm 的国内镜像源进行加速：

js 复制代码

npm install -g cnpm --registry=https://registry.npmmirror.com
验证 cnpm 安装是否成功
cnpm -v

初始化

以 React 组件类型为例，通过以下命令，可以快速初始化一个项目：

js 复制代码

npm init @ice/pkg@latest react-component

选择 React 组件项目类型：

js 复制代码

? 请选择项目类型 (Use arrow keys)
❯ React 组件
  Node 模块
  前端类库  
  Rax 组件

随便输入一个包名，用于测试用的

安装成功

执行 cnpm install 安装依赖

执行 npm start 启动项目

在浏览打开链接，这样就运行成功了

启动项目

js 复制代码

cd react-component
npm start

生成构建产物

js 复制代码

npm run build

发布产物

npm 方式发布

在 package.json 中修改包名
执行发布命令：

js 复制代码

npm publish

发布之前需要先登录 npm，这一步大家自行搜索哈，网上都有的，这里就不重复演示了。

这样就已经发布成功了，去 npm 上看一下

我们随便找个项目装一下试试

在页面中使用试试

js 复制代码

import { PageContainer } from '@ant-design/pro-components';
import NpmPkgTest from 'npm-pkg-test-jacksonchen';
import styles from './index.less';

const HomePage: React.FC = () => {
  // const { name } = useModel('global');
  return (
    <PageContainer ghost>
      <div className={styles.container}>
        {/* <Guide name={trim(name)} /> */}
        <NpmPkgTest title="测试安装效果" />
      </div>
    </PageContainer>
  );
};

export default HomePage;

可以看到和我们预期一致

umd 格式

配置构建参数

在build.config.mts中添加 UMD 配置：

js 复制代码

import { defineConfig } from '@ice/pkg'

// https://pkg.ice.work/reference/config/
export default defineConfig({
  plugins: ['@ice/pkg-plugin-docusaurus'],
  bundle: {
    formats: ['umd'],
    name: 'my-library', // 配置 umd 模块导出的名字，通过 `window[name]` 访问
  },
})

组件全局挂载实现，先写一个简单的试一下

js 复制代码

import * as React from 'react'
import * as ReactDOM from 'react-dom'
import styles from './index.module.css'

interface ComponentProps {
  /** Title for NpmPkgTest. */
  title: string
}

export default function NpmPkgTest(props: ComponentProps) {
  const { title = 'Hello World!' } = props

  return <div className={styles.NpmPkgTest}>{title}</div>
}

// 新增全局挂载方法
export function mountNpmPkgTest(props: ComponentProps) {
  const container = document.createElement('div')
  document.body.appendChild(container)
  ReactDOM.render(<NpmPkgTest {...props} />, container)
  return container
}

// 将组件和方法挂载到全局window对象
if (typeof window !== 'undefined') {
  window.NpmPkgTest = mountNpmPkgTest
}

然后 npm run build

运行成功会打包 dist 文件

浏览器环境测试

构建后生成的 umd 文件可直接在 html 中引用

新建一个 html 文件测试引入 umd 资源是否成功！

别忘了需要引入 js 资源，本地的话就在 dist 文件中

js 复制代码

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>React组件示例</title>
    <script src="../dist/index.umd.es5.production.js"></script>
  </head>
  <body>
    <script>
      // 使用全局挂载方法渲染组件
      window.onload = function () {
        window.NpmPkgTest({
          title: '测试是否成功的',
        })
      }
    </script>
  </body>
</html>

运行 html 文件

可以看到成功了，实战中，只需要将 js 资源发布到 cdn 即可。

总结

通过 ICE PKG 我们实现了一个多场景支持的 NPM 包开发：

npm 方式适合工程化项目依赖管理
und 格式支持直接在浏览器环境通过 cdn 引入
构建配置通过build.config.mts灵活定制
组件需同时支持 ES 模块导入和全局对象访问

实际应用中，可将 und 资源发布到七牛、阿里云等 CDN 服务，通过<script>标签实现零依赖引用，满足不同场景的组件复用需求。