构建并发布 npm 库

发表于 更新于 分类于 阅读次数：

工具库

不兼容库

不兼容指不同时兼容 CommonJS 和 ESM，只能在其中一种模式下运行。

js 库

新创建一个工作目录，执行 npm init -y。修改 package.json 文件，将 type 设置为 mudule 或 commonjs。根据已选择的模块系统进行开发，开发完之后配置 package.json，之后便可直接发布。这种情况适用于开源的较小的库，可以不打包直接发布源码。

ts 库

需要在上述基础上安装 typescript：

1
npm i typescript -D

然后执行 npx tsc --init，会初始化一个 ts.config.json 文件，修改配置文件如下：

1
2
3
4
5
6
7
8
9
10
11
12
{
    "include": ["src/**/*"],
    "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "forceConsistentCasingInFileNames": true,
        "strict": true,
        "skipLibCheck": true,
        "outDir": "./dist"
    }
}

include 指定要编译的 ts 文件的路径，我们一般将业务代码放在 src 目录中。 outDir 指定了存放编译后的 js 文件的目录。若想在 ts 编译时自动生成 .d.ts 文件，增加以下配置：

1
2
3
4
5
{
    "compilerOptions": {
        "declaration": true
    }
}

生成的 .d.ts 文件也存放在 outDir 指定的目录中。最后，编译时，只需要执行

1
tsc

即可。

兼容库

要想兼容 ESM 和 CommonJS，我们需要借助构建工具构建代码。

unbuild

unbuild 是一个轻量级且高效的构建工具，特别适合用于打包 JavaScript/TypeScript 库。它基于 esbuild 提供了快速的构建速度，并且通过简单的配置可以生成多种格式的输出文件（如 ESM、CJS 和 UMD）。
我们在上面 ts 库的基础上安装 unbuild:

1
npm i unbuild -D

由于 unbuild 原生支持 ts，它会自动将 ts 文件编译为 js 文件，因此 tsc 命令只需要进行类型检查，不需要生成 js 文件，向 ts.config.json 添加以下配置：

1
2
3
4
5
{
    "compilerOptions": {
        "noEmit": true
    }
}

然后在 package.json 中添加命令：

1
2
3
4
5
{
    "scripts": {
        "build": "unbuild"
    }
}

unbuild 默认读取 build.config.ts 或 build.config.js 配置文件。
因此在项目根目录下新建 build.config.ts 文件，添加如下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
    // 入口文件
    entries: ["src/index.ts"],
    // 输出目录
    outDir: "dist",
    clean: true,
    // 生成类型声明文件
    declaration: true,
    // 避免因警告中断打包流程
    failOnWarn: false,
    rollup: {
        // 默认只输出 ESM 格式，开启后也可输出 CommonJS 格式
        emitCJS: true
    }
});

然后执行

1
npm run build

会生成 dist 目录，里面包含 index.cjs、index.mjs、index.d.ts 文件。

发布

配置 package.json

需要配置的项包括：

  • name：发布到 npm 上的库名
  • main：CommonJS 环境下的入口文件，相对路径
  • module：ESM 环境下的入口文件，相对路径
  • types：类型声明文件，相对路径
  • exports：可以定义模块的入口点（替代 main），并且可以控制如何导出模块
  • keywords：关键字，用于在 npm 仓库搜索
  • files: 指定将哪些文件发布到 npm 仓库

以下是一个示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
    "name": "vite-plugin-obfuscator-ts",
    "version": "1.0.0",
    "main": "./dist/index.cjs",
    "module": "./dist/index.mjs",
    "types": "./dist/index.d.ts",
    "type": "module",
    "exports": {
        ".": {
            "types": "./src/index.d.ts",
            "import": "./dist/index.mjs",
            "require": "./dist/index.cjs"
        }
    },
    "keywords": ["vite", "plugin", "obfuscator", "typescript"],
    "author": "Silence",
    "license": "ISC",
    "description": "A vite obfuscator plugin based on typescript",
    "files": ["dist", "package.json", "README.md"],
    "scripts": {
        "build": "unbuild"
    },
    "dependencies": {
        "chalk": "^5.4.1",
        "javascript-obfuscator": "^4.1.1",
        "minimatch": "^10.0.1",
        "ora": "^8.1.1"
    },
    "devDependencies": {
        "@types/node": "^22.10.5",
        "typescript": "^5.7.2",
        "unbuild": "^3.3.1"
    }
}
上传到 npm 仓库
注册 npm 账号

想要发布到 npm 仓库，就必须要有一个账号，先去 npm 官网注册一个账号，注意记住用户名、密码和邮箱，发布的时候会用到。

设置 npm 源

在国内很多小伙伴喜欢把本地的 npm 镜像源采用的是淘宝镜像源或者其它的，如果想要发布 npm 包，我们得把我们的 npm 源切换为官方得源，命令如下：

1
npm config set registry=https://registry.npmjs.org

或者执行命令时指定仓库源为官方源。

登录

在打包后的文件根目录打开终端，输入一下指令登录到官网：

1
npm login --registry=https://registry.npmjs.org

会提示你输入账号密码。此外，还会给你邮箱发送一个一次性密码让你输入。

推送到 npm 仓库
1
npm publish --registry=https://registry.npmjs.org

注意：发布前要保证没有相同的包名，否则无法发布，每次发布的版本号必须不同。
当修改了一些东西再次发布的时候希望版本号自动 +1，可以执行：

1
2
npm version patch
npm publish

之后，你就可以在 npm 官网自己的仓库中看到了。

组件库

1. 新建项目

1
npm init vue@latest

2. 创建要构建的组件

例如我们要封装一个文件上传的组件，在 src/components 目录下新建文件夹 silence-file-upload，具体目录结构如下：

1
2
3
4
5
6
7
8
9
> components
    > silence-file-upload
        > src
        |    > components
        |    > utils
        |    > types
        |        index.d.ts
        index.vue
        main.ts
  • index.vue：存放组件的主要代码；
  • main.ts：组件的入口文件；
  • src/components：存放 index.vue 中用到的次级组件；
  • src/utils：存放一些工具类的方法/函数；
  • src/types：存放类型声明文件

编写完组件的主要代码后，在 main.ts 文件中添加如下代码：

1
2
3
4
5
6
7
8
9
import silenceFileUpload from "./index.vue";
import type { App } from "vue";


export default {
    install: (app: App) => {
        app.component("SilenceFileUpload", silenceFileUpload);
    }
}

install 方法可以使组件在被使用 app.use() 注册后生效。

3. 本地验证

我们可以先在本地验证组件是否正常运行。
在项目根目录下的 src/main.ts 中注册组件：

1
2
3
4
5
6
7
8
import { createApp } from 'vue'
import App from './App.vue'
import SilenceFileUpload from "@/components/silence-file-upload/index";

const app = createApp(App)
app.use(SilenceFileUpload)

app.mount('#app')

运行项目之后就可以看到组件是否正常运行。

4. 构建输出

在项目的根目录的 vite.config.ts 中修改相关配置，修改成组件库打包模式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import { fileURLToPath, URL } from 'node:url'
import { resolve } from "path"
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'


export default defineConfig({
    plugins: [
        vue()
    ],
    resolve: {
        alias: {
            '@': fileURLToPath(new URL('./src', import.meta.url))
        }
    },
    build: {
        // 打包后输出的文件夹
        outDir: "silence-file-upload",
        // 库打包模式
        lib: {
            // 入口文件
            entry: resolve(__dirname, "./src/components/silence-file-upload/main.ts"),
            // name 是暴露的全局变量
            name: "SilenceFileUpload",
            // fileName 默认是 package.json 的 name
            fileName: "silence-file-upload"
        },
        rollupOptions: {
            // 外部化处理那些不想被打包进库的依赖
            external: ["vue", "element-plus"],
            output: {
                // 在 UMD 构建模式下为这些外部化的依赖提供一个全局变量
                globals: {
                    vue: "Vue",
                    "element-plus": "ElememtPlus"
                }
            }
        }
    }
})

然后执行 npm run build，在根目录下出现文件夹 silence-file-upload：

1
2
3
4
> silence-file-upload
    silence-file-upload.mjs
    silence-file-upload.umd.js
    style.css

5. 上传到 npm

5.1 准备工作
5.1.1 添加 README.md

添加一些对该组件的介绍以及使用说明。

5.1.2 添加 ts 声明文件

在打包好的 silence-file-upload 目录下新建 index.d.ts 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 添加一些开发者可能用到的接口、类型、函数、命名空间等，如
export interface Files {
    fileName: string;
    filePath?: string;
    status?: "success" | "error" | "uploading";
    key?: string;
    isMounseHover?: boolean;
    progress?: number;
}

declare const default_: {
    install: (app: any) => void
}

export default default_;
5.1.3 配置 package.json

首先我们在打包好的 silence-file-upload 目录下，打开终端，然后执行 npm init -y 命令初始化 package.json。
然后进行如下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "silence-file-upload",
  "version": "1.0.0",
  "private": false,
  "typings": "index.d.ts", // 配置声明文件
  "description": "文件上传组件",
  "main": "silence-file-upload.umd.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  // 在 npm 上可搜索的关键字
  "keywords": [
    "upload",
    "fileUpload",
    "file",
    "file-upload"
  ],
  "author": "",
  "license": "ISC"
}
5.2 上传到 npm

同上。

6. 下载与使用

安装
1
npm i silence-file-upload

注意：这里仍然要用 npm 官方源。
然后，就可以在 node_modules 中找到我们的库了。

引入

在 main.ts 中添加：

1
2
3
4
import SilenceFileUpload from "silence-file-upload";
import "silence-file-upload/style.css";

app.use(SilenceFileUpload);
使用
1
<silence-file-upload v-model="fileList" />

拓展

在库模式下，如果我们的代码中引入了外部依赖（包括 CDN 链接），那么这些依赖在打包时会被编译进来。

如果我们想减小包的体积，不想将这些依赖打包进来，就需要用到 rollup 的 external 属性。该属性可以将匹配到的模块进行外部化处理，那什么是外部化处理呢？

比如我们有以下代码：

1
2
import { ref, watch } from "vue";
import { ElMessage } from "element-plus";

这里“vue” 和 “element-plus”就是依赖，如果我们直接打包，打包后的代码中就不会出现

1
2
import { ref, watch } from "vue";
import { ElMessage } from "element-plus";

而是被直接编译了进来，这也意味着当人们使用它时，不需要额外安装“vue” 和 “element-plus”。但是这样做的后果就是打包后的代码可能会有成千上万行，影响性能。

如果进行了外部化处理，你可以在打包后的代码中看到类似这样的内容：

1
2
import xxx from "vue";
import xxx from "element-plus";

“vue” 和 “element-plus”被从外部导入了，他们没有被编译进来，这时包的体积可能只有几百行代码。但是在使用这个库时，需要额外安装这两个依赖。

想要在安装库时自动安装该库所需要的依赖，可以在发布前在 package.json 中配置 dependencies：

1
2
3
4
"dependencies": {
    "vue": "^3.2.47",
    "element-plus": "^2.3.4"
  }
devDependencies 和 dependencies

npm 包声明会添加到 dependencies 或者 devDependencies 中。dependencies 中声明的是项目在生产环境中所必需的包。devDependencies 中声明的是开发阶段需要的包，如 Webpack、ESLint、Babel 等，用来辅助开发。打包上线时并不需要这些包，所以要根据包的实际用途把它们声明在适当的位置。