创建与发布包

把可复用逻辑做成 npm 包：正确 package.json、入口导出、files 白名单与 npm publish。内部工具包与开源包流程相同，差别在 registry 与 nva-semver 纪律。

学习目标

• 搭建可发布的包目录结构（ESM）
• 配置 exports、bin 与 files
• 了解 publish 前检查与版本 bump

最小可发布包

my-utils/
  package.json
  src/index.js
  README.md

{
  "name": "@codermap/my-utils",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": "./src/index.js"
  },
  "files": ["src", "README.md"],
  "engines": { "node": ">=20" }
}

files 控制 tarball 内容——避免把测试、草稿 markdown 发上去。

本地开发与链接

npm pack          # 生成 .tgz，检查体积与内容
npm link          # 全局 link
cd ../consumer && npm link @codermap/my-utils

在 nodejs-essentials 项目里验证 import 路径与类型（若写 .d.ts）。

CLI 包：bin 字段

{
  "bin": {
    "my-import": "./bin/my-import.js"
  }
}

#!/usr/bin/env node
import { main } from "../src/cli.js";
main().catch((err) => {
  console.error(err.message);
  process.exit(1);
});

shebang + 可执行权限；细节在 nva-cli。

发布流程

1. npm login（或 CI token）
2. npm test（见 testing-essentials）
3. npm version patch|minor|major
4. npm publish --access public   # scoped 包默认 private
5. git push --follow-tags

禁止 把 .env、npm token 写进仓库；CI 用 secret 注入。

与 Nest monorepo 的关系

业务 API 在 nestjs-essentials 应用内；跨项目共享 的纯函数、CLI 才抽成包。数据库 migration 脚本可独立包，驱动用法见 nva-db。

练习

• npm pack 后解压 .tgz，确认无多余文件
• 为包写 2 个 用例