开发与维护nodejs工具库或自定义npm包
目录
开发与维护nodejs工具库或自定义npm包
一、初始设置：为成功发布做好准备
1. 项目初始化与结构
bash
# 创建项目目录并初始化
mkdir my-awesome-lib
cd my-awesome-lib
npm init -y推荐的项目结构：
text
my-awesome-lib/
├── src/ # 源代码目录
│ └── index.js # 主入口文件
├── dist/ # 构建输出目录（如果需要打包）
├── test/ # 测试文件
├── docs/ # 文档
├── examples/ # 使用示例
├── .github/ # GitHub 配置（workflows, ISSUE_TEMPLATE等）
├── package.json
├── README.md
└── .npmignore # 可选，控制发布到npm的文件2. 关键的 package.json 配置
一个库的 package.json 配置与应用项目不同：
json
{
"name": "my-awesome-lib", // 确保名字唯一且有意义
"version": "1.0.0", // 遵循语义化版本规范
"description": "A brief description of your awesome library",
"main": "dist/index.js", // CommonJS 入口点
"module": "src/index.js", // ES Module 入口点 (如果支持)
"types": "dist/index.d.ts", // TypeScript 类型定义文件
"files": [ // 明确指定要发布到npm的文件
"dist",
"src", // 可选：发布源码以供tree-shaking
"README.md"
],
"scripts": {
"build": "babel src -d dist --copy-files",
"test": "jest",
"prepublishOnly": "npm run build && npm test", // 发布前自动构建和测试
"version": "npm run build" // 执行npm version时自动构建
},
"keywords": ["tool", "utility", "awesome"],
"author": "Your Name",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/your-username/my-awesome-lib.git"
},
"bugs": {
"url": "https://github.com/your-username/my-awesome-lib/issues"
},
"homepage": "https://github.com/your-username/my-awesome-lib#readme",
"devDependencies": {
// 开发工具...
},
"peerDependencies": {
// 如果需要：如 "react": ">=16.8.0"
},
"engines": {
"node": ">=14.0.0" // 指定支持的Node.js版本
}
}二、开发规范与工具链
1. 代码质量与风格
bash
# 安装必要的开发依赖
npm install --save-dev eslint prettier eslint-config-prettier @typescript-eslint/eslint-plugin @typescript-eslint/parser.eslintrc.js 配置示例：
javascript
module.exports = {
env: {
node: true,
es2021: true,
},
extends: [
'eslint:recommended',
'prettier' // 确保ESLint和Prettier不冲突
],
parserOptions: {
ecmaVersion: 12,
sourceType: 'module',
},
rules: {
// 自定义规则
},
};2. 测试框架
bash
npm install --save-dev jest ts-jest @types/jestjest.config.js 配置：
javascript
module.exports = {
preset: 'ts-jest',
testEnvironment: 'node',
testMatch: ['**/test/**/*.test.ts'],
collectCoverageFrom: ['src/**/*.ts'],
coverageDirectory: 'coverage',
};3. 构建与打包
根据目标用户选择构建工具：
- Rollup: 适合库打包，Tree-shaking友好
- Babel: 转换现代JS语法
- TypeScript: 类型安全和编译
bash
npm install --save-dev @babel/core @babel/preset-env rollup @rollup/plugin-babel三、版本控制与发布流程
1. 语义化版本 (SemVer)
遵循 MAJOR.MINOR.PATCH 规则：
- PATCH (1.0.1): 向后兼容的bug修复
- MINOR (1.1.0): 向后兼容的新功能
- MAJOR (2.0.0): 不兼容的API变更
2. 自动化发布流程
使用 npm version 命令管理版本：
bash
# 开发完成后...
npm test # 确保测试通过
npm run build # 构建生产版本
# 更新版本号（选择其一）
npm version patch # 1.0.0 → 1.0.1
npm version minor # 1.0.1 → 1.1.0
npm version major # 1.1.0 → 2.0.0
# 发布到npm
npm publish
# 推送到GitHub并打tag
git push && git push --tags3. 使用发布脚本自动化
在 package.json 中添加钩子：
json
{
"scripts": {
"preversion": "npm test",
"version": "npm run build && git add -A dist",
"postversion": "git push && git push --tags"
}
}四、文档编写：让用户爱上你的库
1. - 你的门面
一个优秀的 README 应包含：
markdown
# My Awesome Lib
[](https://badge.fury.io/js/my-awesome-lib)
[](https://github.com/your-username/my-awesome-lib/actions)
[](https://coveralls.io/github/your-username/my-awesome-lib)
> 一句话描述库的价值
## ✨ Features
- 功能点1
- 功能点2
- 功能点3
## 📦 Installation
```bash
npm install my-awesome-lib
# 或
yarn add my-awesome-lib🚀 Quick Start
javascript
import { awesomeFunction } from 'my-awesome-lib';
const result = awesomeFunction('input');
console.log(result); // 'Awesome output!'📚 API Reference
awesomeFunction(input: string): string
详细描述函数的作用、参数、返回值。
Example:
javascript
// 代码示例🤝 Contributing
欢迎贡献！请阅读 。
📄 License
MIT ©
text
#### 2. 高级文档工具
- **TypeDoc**: 为TypeScript项目自动生成API文档
- **JSDoc**: JavaScript项目的文档生成
- **VitePress/VuePress**: 构建完整的文档网站
---
### 五、维护与迭代最佳实践
#### 1. GitHub配置
创建 `.github` 目录来规范协作：.github/
├── ISSUE_TEMPLATE/
│ ├── bug_
│ └── feature_request.md
├── PULL_REQUEST_TEMPLATE.md
└── workflows/
└── ci.yml
text
**示例 CI 工作流 (`.github/workflows/ci.yml`)**:
```yaml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [14.x, 16.x, 18.x]
steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm test
- run: npm run build2. 变更日志 ( )
使用 并自动生成变更日志：
bash
# 安装工具
npm install --save-dev conventional-changelog-cli
# 在package.json中添加脚本
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
}
}3. 处理Issue和PR
- 使用模板规范Issue报告
- 建立清晰的贡献指南
- 及时响应社区反馈
六、实战案例：发布一个工具函数库
1. 开发阶段
bash
# 初始化
npm init -y
# 添加开发依赖
npm install --save-dev jest @types/jest typescript @babel/core @babel/preset-env
# 添加源码
mkdir src
echo "export const add = (a, b) => a + b;" > src/index.js
# 添加测试
mkdir test
echo "const { add } = require('../src'); test('adds 1 + 2 to equal 3', () => { expect(add(1, 2)).toBe(3); });" > test/index.test.js2. 发布准备
json
{
"main": "src/index.js",
"files": ["src", "README.md"],
"scripts": {
"test": "jest",
"prepublishOnly": "npm test"
}
}3. 首次发布
bash
# 登录npm（如果第一次）
npm login
# 发布
npm publish
# 或者发布测试版
npm version prepatch --preid=beta
npm publish --tag beta4. 迭代更新
bash
# 修复bug后发布补丁版本
npm version patch
npm publish
# 添加新功能后发布小版本
npm version minor
npm publish
# 用户可以通过指定tag安装测试版
npm install my-awesome-lib@beta七、高级技巧与陷阱避免
- 作用域包：使用
@username/package-name避免命名冲突 - 多入口点：大型库可以拆分多个入口
- 条件导出：为不同环境提供不同的入口点
- 避免全局副作用：确保库的纯净性
- 浏览器兼容性：如果需要，提供UMD构建版本
- TypeScript支持：即使用JS开发，也提供类型定义
记住，一个好的库不仅仅是代码，还包括文档、测试和社区支持