跳到主要内容

npm 包其他构建

· 阅读需 8 分钟

一个基本包在构建时还需要考虑的其他方面的内容。

模块化与架构设计​

模块化分割​

  • 按功能划分：将核心逻辑、业务逻辑、工具函数等，分别打包到不同的模块中，方便维护和复用。
  • 支持插件系统：允许用户自定义插件，实现对不同环境、不同场景的兼容。
class MyPackage {
  constructor() {
    // 初始化
  }
  // 业务逻辑
  doSomething() {
    // ...
  }
  // 工具函数
  utils() {
    // ...
  }
  // 插件系统
  use(plugin) {
    // ...
  }
}

多环境兼容​

输出多种格式，如： ESM、CJS、UMD、IIFE

// package.json
{
  "main": "./dist/index.cjs", // CommonJS
  "module": "./dist/index.esm.js", // ESM
  "browser": "./dist/index.umd.js", // 浏览器环境
  "types": "./dist/index.d.ts", // TypeScript 类型定义
}

tree Shaking 优化​

在 package.json 中配置 sideEffects 属性，来告诉 webpack 在构建过程中，哪些文件可以安全地被 tree shaking。

// package.json
{
  "sideEffects": false,
}

文档和示例​

  • 提供文档：包括使用说明、示例代码、API 文档等，帮助用户快速上手和了解如何使用。
  • 提供示例：提供示例代码，帮助用户快速了解如何使用。

自动化文档生成​

  • 工具选择：如 typedoc、jsdoc 等。
  • 配置：根据项目实际情况进行配置，确保生成的文档符合要求。
  • 持续集成：在每次构建时，自动生成文档，并保存到仓库中，以便随时查阅。
  • 托管文档：通过 GitHub Pages、GitLab Pages 等服务托管文档，便于用户访问。

示例代码​

  • 提供示例代码：包括完整的示例代码，帮助用户快速了解如何使用。
  • 创建 CodeSandbox：使用 CodeSandbox 或 StackBlitz 等类似工具，创建示例代码，方便用户在线调试和查看。

README 规范​

  • 必要的内容：安装说明、快速上手、API 文档、贡献指南、许可证
  • 徽章：显示测试覆盖率、版本号、下载量等

示例：

![version](<https://img.shields.io/npm/v/a-type-of-js.svg?logo=npm&logoColor=rgb(0,0,0)&label=version&labelColor=rgb(73,73,228)&color=rgb(0,0,0)>)
![NPM Last Update](<https://img.shields.io/npm/last-update/a-type-of-js?logo=npm&labelColor=rgb(255,36,63)&color=rgb(0,0,0)>)
![📦 size](<https://img.shields.io/bundlephobia/minzip/a-type-of-js.svg?logo=npm&labelColor=rgb(201,158,140)&color=rgb(0,0,0)>)
![downloads](<https://img.shields.io/npm/dm/a-type-of-js.svg?logo=npm&logoColor=rgb(0,0,0)&labelColor=rgb(194,112,210)&color=rgb(0,0,0)>)
![downloads](<https://img.shields.io/npm/dt/a-type-of-js.svg?logo=npm&labelColor=rgb(107,187,124)&color=rgb(0,0,0)>)

![last commit](<https://img.shields.io/github/last-commit/earthnutDev/a-type-of-js.svg?logo=github&logoColor=rgb(0,0,0)&labelColor=rgb(255,165,0)&color=rgb(0,0,0)>)
![GitHub commit activity](<https://img.shields.io/github/commit-activity/y/earthnutDev/a-type-of-js.svg?logo=github&labelColor=rgb(128,0,128)&color=rgb(0,0,0)>)
![test coverage](<https://img.shields.io/codecov/c/gh/earthnutDev/a-type-of-js.svg?logo=codecov&labelColor=rgb(0,0,0)&color=rgb(0,0,0)>)

效果展示：

version NPM Last Update 📦 size downloads downloads

last commit GitHub commit activity test coverage

版本管理与发布​

语义话版本管理​

语义化版本管理：使用语义化版本管理，如 SemVer，以 major.minor.patch 的形式进行版本管理。

  • major : 不兼容的 API 变更
  • minor : 添加新的功能，不破坏现有 API 的功能
  • patch : 修复 bug，不破坏现有 API 的功能

自动化发布​

使用工具 standard-version 或 semantic-release 自动化版本管理，并使用 npm publish 发布包。

{
  "scripts": {
    "release": "standard-version && git push --follow-tags && npm publish",
  },
}

版本回退​

在发布过程中，如果发现版本号错误，可以使用 npm deprecate 进行版本回退，并在文档中说明替代方案。

依赖与安全​

依赖优化​

  • 避免使用过时的依赖：使用最新、安全的依赖，避免使用过时的依赖。

  • 避免使用开发依赖：开发依赖只用于开发阶段，发布时无需包含。

  • 避免使用重复依赖：避免重复依赖，使用统一的依赖管理工具进行依赖管理。

  • 生产依赖（dependencies）： 仅保留运行时必须的包

  • 开发依赖（devDependencies）：构建、测试、格式化、文档、自动化等工具

安全性​

  • 避免使用不安全的依赖：使用安全的依赖，避免使用不安全的依赖。
  • 避免使用不安全的插件：使用安全的插件，避免使用不安全的插件。
  • 使用 npm audit 进行依赖漏洞扫描，并使用 npm audit fix 进行修复。
  • 使用 npm shrinkwrap 进行依赖锁定，以防止依赖版本升级带来的问题。
  • 使用 npm dedupe 进行依赖树优化，减少重复依赖。
  • 使用 npm prune 进行依赖清理，删除未使用的依赖。
  • 使用 npm cache clean 进行缓存清理，避免缓存影响构建结果。
  • 使用 npm update 进行依赖更新，以获取最新版本的依赖。

用户体验增强​

类型声明​

提供 .d.ts 文件，用于提供类型声明，以增强用户体验。

错误处理​

  • 自定义错误类型：帮助用户或自己快速地处理错误，避免用户 sightseeing
  • 输入验证：一行代码写功能，百行代码防刁民

性能优化​

  • 使用 webpack 或 rollup 进行打包，以减少包体积。
  • 使用 lodash 或 ramda 等工具库，以减少重复代码。
  • 使用 babel 或 swc 进行编译，以减少编译时间。
  • 使用 tree-shaking 进行摇掉无用的代码。
  • 使用 lazy loading 进行懒加载，以减少首屏加载时间。
  • 使用 async/await 或 generator 进行异步编程，以减少回调嵌套。
  • 使用 benchmark 库进行性能测试，以确定代码性能。
  • 避免阻塞主进程（Node.js 使用 worker_threads，浏览器环境使用 web worker）

社区与协作​

贡献指南​

  • 创建 CONTRIBUTING.md 文件，以描述如何贡献代码。
  • 创建 PULL_REQUEST_TEMPLATE.md 文件，以描述拉取请求模板。
  • 创建 ISSUE_TEMPLATE.md 文件，以描述问题模板。
  • 创建 SECURITY.md 文件，以描述安全漏洞处理流程。
  • 创建 CHANGELOG.md 文件，以记录版本更新日志。
  • 创建 LICENSE.md 文件，以描述开源协议。
  • 创建 README.md 文件，以描述项目简介。
  • 创建 CONTRIBUTORS.md 文件，以记录贡献者名单。
  • 提供 Issue 模板，以帮助用户提交问题。

行为规范​

  • 创建 CODE_OF_CONDUCT.md 文件，以描述社区行为规范。

多语言支持​

如果面向国际化用户，提供多语言的文档和错误信息

扩展性设计​

配置文件支持​

允许用户通过配置文件进行配置，以增强用户体验。

声明周期 🪝​

暴露 🪝 函数，供用户扩展

插件生态​

提供插件开发文档和示例，鼓励社区贡献插件

监控与维护​

使用统计​

可匿名 📉，了解功能使用情况

维护模式​

如果项目进入维护期，在文档和 README 中添加维护模式说明

弃用策略​

提前告知用户即将废弃的功能，并给出替代方案