Skip to main content

开发 Package

[[toc]]

package.json 要求​

https://docs.npmjs.com/creating-a-package-json-file

https://docs.npmjs.com/cli/v8/configuring-npm/package-json

name 要有 scope 前缀​

scope 前缀对应的是 gitlab 上的 group 名称。

{
	"name": "@yitasoft-team:xxx",
}

一定要加 files 白名单​

  • 一定要定白名单，哪些文件要被打包，防止信息泄露

  • 目录的话要在前面加斜杠，例如 "/lib"；否则，如果你有一个类似 "test/lib"的目录，它也将被包含在内

  • /lib 对应的是 CommonJS 规范的模块（可直接在 node.js 使用的模块）

{
  "files": [
    "/lib", 
    "/dist",
    "/es"
  ],
}

将 main 指向 CommonJs 规范的 ES5 模块入口​

main 字段指向的应该是编译后生成的 ES5 版本的代码（CommonJs 规范）。

简单来说就是你的入口文件的语法是 module.exports = {} 的。

将 module 指向采用类 ES Module 规范的 ES6 模块入口​

简单来说就是你的入口文件的语法是 export {} 的。

https://zhuanlan.zhihu.com/p/34164963

各种模块规范整理​

可参考 Rollup 文档的解释：https://cn.rollupjs.org/configuration-options/#output-format

  • amd – 异步模块加载，适用于 RequireJS 等模块加载器
  • cjs – CommonJS，适用于 Node 环境和其他打包工具（别名：commonjs）
  • es – 将 bundle 保留为 ES 模块文件，适用于其他打包工具，以及支持 <script type=module> 标签的浏览器。（别名：esm，module）
  • iife – 自执行函数，适用于 <script> 标签（如果你想为你的应用程序创建 bundle，那么你可能会使用它）。iife 表示“自执行 函数表达式”
  • umd – 通用模块定义规范，同时支持 amd，cjs 和 iife
  • system – SystemJS 模块加载器的原生格式（别名：systemjs）

配 exports 别名​

这个是 webpack 一直以来的专有属性，可用于做 import 时的路径转换（以使用者角度）。
该属性 npm 的文档虽然没有介绍，但其实也一早就支持了。

注意点：

  • 若设置 exports 一定/必须/记住要有根路径 . 的指向入口文件。因为此时 package.json module 属性将会被忽略。
// package.json
{
  "exports": {
    ".": "./index.js",
    "./styles/": "./src/styles/",
    "./components/": "./src/components/"
  }
}

发布 NPM 包（私服）​

若未配 .npmrc 则必须将私库地址加到 publishConfig​

否则，执行 npm publish 时，会向 npm 默认的 registry 发布 package。

我们还可以在 package 打包之前，覆盖 manifest 中的某些字段。
以下字段可以被覆盖：https://pnpm.io/zh/package_json#publishconfig

示例：

  "publishConfig": {
    "@yitasoft-team:registry": "https://xxx/api/v4/projects/xxx/packages/npm/"
  },

NPM 私服配置及使用​

仅限内部访问： https://thoughts.teambition.com/workspaces/5f4e0d8cb9883f0016b6d89e/docs/6256a4fdfb49bf00016a8e98

Workplaces 特性​

https://docs.npmjs.com/cli/v7/using-npm/workspaces/

可以将项目内的多个子包，提升至项目根(顶层)空间上使用。

以前没有该机制时，我们需要在项目根目录 npm install 本地子模块 或者 npm link 本地子模块 才能达到类似效果。

配置项目级别的 .npmrc​

https://docs.npmjs.com/cli/v8/configuring-npm/npmrc

同一个 version 只能发布一次​

要确保每次发布时都是万无一失。

在真正执行 npm publish 前，要使用 npm publish --dry-run 模拟一下。

使用了 npm publish 会自动创建一个与 version 对应的 git tag​

version 版本号要严格遵循规范​

规范：https://semver.org/lang/zh-CN/

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality in a backward compatible manner
  3. PATCH version when you make backward compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

semantic-release 必备的自动化发布工具​

semantic-release Fully automated version management and package publishing https://github.com/semantic-release/semantic-release

官方文档：https://semantic-release.gitbook.io/semantic-release/

自动生成 CHANGELOG.md​

借助插件 @semantic-release/changelog 每次发布版本的时候，都自动将新特性写入 CHANGELOG.md 文件。

https://github.com/semantic-release/changelog

注意：changelogTitle 并非文档标题。它会在每次更新时都会生成一次，即每条更新日志前面都会有该 title，且 title 为空时还会抛出错误导致后续的 git 等流程被中断，非常不好用。建议不使用该配置。

注意 @semantic-release/git 默认不会自动提交 CHANGELOG.md 文件，需要手动加配置（不要漏了package.json 等文件）：

[
  "@semantic-release/git",
  {
    "assets": [
      "package.json",
      "package-lock.json",
      "docs/CHANGELOG.md"
    ]
  }
]

配合 GitLab CI/CD 自动发布 Package​

GitLab CI 集成 semantic-release: http://106.52.110.79/help/ci/examples/semantic-release.md

GitLab 官方的使用示例：

semantic-release-npm An example project that uses semantic-release to automate the publishing of NPM packages to GitLab's Package Registry https://gitlab.com/gitlab-examples/semantic-release-npm