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

JacksonChen
200 阅读3分钟

前言

在开发中，我们经常需要将功能模块封装为 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 的国内镜像源进行加速：

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

初始化

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

npm init @ice/pkg@latest react-component

选择 React 组件项目类型：

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

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

安装成功

执行 cnpm install 安装依赖

执行 npm start 启动项目

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

启动项目

cd react-component
npm start

生成构建产物

npm run build

发布产物

npm 方式发布

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

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

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

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

在页面中使用试试

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 配置：

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]` 访问
  },
})

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

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 文件中

<!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 包开发：

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

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

avatar
文章
阅读
粉丝