npm-publish-tool

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

npm Publish Tool

npm 发布工具

Use Bun as the package manager and release runner. Publish standard npm-compatible artifacts. Make the project conform to one of the two approved layouts below, then run the complete publishing workflow. Apply the package-shape and registry advice in the npm publishing research through Bun commands.

使用Bun作为包管理器和发布执行工具。发布标准的npm兼容制品。让项目符合以下两种已批准的布局之一，然后运行完整的发布工作流。通过Bun命令应用npm发布研究文档中的包结构和注册表建议。

Approved Layouts

已批准的布局

1. One package

1. 单包布局

text

<package-root>/
  src/
    index.ts
    cli.ts      # CLI packages only
  dist/         # generated JavaScript and declarations
  package.json
  bun.lock
  README.md
  LICENSE

The package must:

Declare Bun in
```
packageManager
```
and use
```
bun.lock
```
as its only lockfile.
Ship compiled JavaScript and
```
.d.ts
```
files from
```
dist/
```
.
Declare its public API with
```
exports
```
, including
```
types
```
, and point
```
types
```
at
```
dist/index.d.ts
```
.
Use
```
files: ["dist"]
```
.
Provide a
```
build
```
script and run it from
```
prepublishOnly
```
.
Declare
```
bin
```
only for a CLI. Its compiled target must start with
```
#!/usr/bin/env node
```
and be executable.
Put host tools such as ESLint, Prettier, Vite, and TypeScript in
```
peerDependencies
```
when the package plugs into their process.

text

<package-root>/
  src/
    index.ts
    cli.ts      # 仅CLI包需要
  dist/         # 生成的JavaScript和声明文件
  package.json
  bun.lock
  README.md
  LICENSE

该包必须满足：

在
```
packageManager
```
中声明Bun，并将
```
bun.lock
```
作为唯一的锁文件。
从
```
dist/
```
目录发布编译后的JavaScript和
```
.d.ts
```
文件。
使用
```
exports
```
声明公共API，包括
```
types
```
字段，并将
```
types
```
指向
```
dist/index.d.ts
```
。
设置
```
files: ["dist"]
```
。
提供
```
build
```
脚本，并在
```
prepublishOnly
```
阶段执行它。
仅针对CLI包声明
```
bin
```
字段。其编译后的目标文件必须以
```
#!/usr/bin/env node
```
开头且具备可执行权限。
当包需要接入ESLint、Prettier、Vite和TypeScript等宿主工具的流程时，将这些工具放入
```
peerDependencies
```
。

2. Package monorepo

2. 包单仓库布局

text

<repo-root>/
  package.json    # private Bun-workspaces root
  bun.lock       # the only lockfile
  <workspace-dir>/
    <package>/   # conforms to layout 1

The root

package.json

must set

private: true

, declare Bun in

packageManager

, declare workspace globs that cover every package, and provide root commands that build and test all workspaces with Bun. Preserve existing Bun-compatible workspace directories and globs. Every publishable workspace must independently conform to layout 1's source, output, documentation, and manifest rules while using the root

bun.lock

. Never publish the workspace root.

text

<repo-root>/
  package.json    # 私有Bun工作区根目录
  bun.lock       # 唯一的锁文件
  <workspace-dir>/
    <package>/   # 符合布局1的要求

根目录的

package.json

必须设置

private: true

，在

packageManager

中声明Bun，声明覆盖所有包的工作区通配符，并提供通过Bun构建和测试所有工作区的根命令。保留现有的Bun兼容工作区目录和通配符。每个可发布的工作区必须独立符合布局1的源码、输出、文档和清单规则，同时使用根目录的

bun.lock

。禁止发布工作区根目录。

Workflow

工作流

Read the repository instructions, manifests, source, lockfiles, and release configuration. Classify the project as one package or a package monorepo.
Enforce the matching approved layout before release:
- For a standalone repository, normalize its package to layout 1.
- For a repository with workspaces, multiple package roots, or a package nested beneath a monorepo root, normalize or create the layout 2 Bun-workspaces root and normalize every publishable package to layout 1. Keep the monorepo layout even when only one workspace is publishable. Preserve existing Bun-compatible workspace paths and globs.
- Replace npm, pnpm, and Yarn lockfiles and package-manager commands with Bun.
- Keep an existing build or release tool only when Bun can run it and it produces the required artifact. Otherwise, configure the simplest Bun and TypeScript setup that does.
Apply the requested semantic version with the project's working release workflow through
```
bun
```
or
```
bunx
```
. When none exists, use
```
bun pm version <version>
```
. For a monorepo, finalize every released package version and its internal workspace dependency ranges before creating the release lockfile.
Run
```
bun install
```
after versioning to create or update the authoritative
```
bun.lock
```
, then run
```
bun install --frozen-lockfile
```
. Run the build and normal tests with
```
bun run
```
. In a monorepo, run workspace scripts from the root with
```
bun run --workspaces <script>
```
.
From each package being released, run
```
bun pm pack
```
. Inspect the generated
```
.tgz
```
with
```
tar -tzf
```
. Confirm that compiled runtime files, declarations, package metadata, README, and license are present and that source, tests, fixtures, local configuration, and secrets are absent.
Create a temporary fixture project with Bun, install each generated
```
.tgz
```
with
```
bun add
```
, and exercise the documented normal import with Bun. For a CLI package, also run its documented normal command through the installed binary and confirm the shebang and executable bit.
Publish the exact artifact that passed the fixture test with
```
bun publish <generated-tarball>
```
. Use a trusted CI release workflow configured to install and run Bun when present. Stop after verification when the request is only to set up, prepare, pack, or test the package.
Report the approved layout, Bun setup changes, package names and versions, artifact paths, checks run, and publish result. Keep generated tarballs only when they are requested outputs.

Convert every nonconforming project before publishing. Use Bun for every package-management and release command.

读取仓库说明、清单、源代码、锁文件和发布配置。将项目归类为单包或包单仓库。
在发布前强制执行匹配的已批准布局：
- 对于独立仓库，将其包标准化为布局1。
- 对于包含工作区、多个包根目录或嵌套在单仓库根目录下的包，标准化或创建布局2的Bun工作区根目录，并将每个可发布的包标准化为布局1。即使只有一个工作区可发布，也要保留单仓库布局。保留现有的Bun兼容工作区路径和通配符。
- 用Bun替换npm、pnpm和Yarn的锁文件及包管理器命令。
- 仅当Bun可以运行现有构建或发布工具且能生成所需制品时，才保留该工具。否则，配置最简单的Bun和TypeScript环境来实现需求。
通过
```
bun
```
或
```
bunx
```
，按照项目现有的发布工作流应用请求的语义化版本。如果没有现有工作流，使用
```
bun pm version <version>
```
。对于单仓库，在创建发布锁文件之前，确定每个待发布包的版本及其内部工作区依赖范围。
版本控制后运行
```
bun install
```
以创建或更新权威的
```
bun.lock
```
，然后运行
```
bun install --frozen-lockfile
```
。使用
```
bun run
```
执行构建和常规测试。在单仓库中，从根目录使用
```
bun run --workspaces <script>
```
运行工作区脚本。
对每个待发布的包，运行
```
bun pm pack
```
。使用
```
tar -tzf
```
检查生成的
```
.tgz
```
文件。确认编译后的运行时文件、声明文件、包元数据、README和许可证已包含，且源码、测试、 fixtures、本地配置和机密信息已排除。
使用Bun创建临时测试项目，通过
```
bun add
```
安装每个生成的
```
.tgz
```
文件，并使用Bun测试文档中记录的常规导入方式。对于CLI包，还需通过安装后的二进制文件运行其文档中记录的常规命令，并确认shebang和可执行权限。
使用
```
bun publish <generated-tarball>
```
发布通过测试的制品。如果存在可信的CI发布工作流，配置其安装并运行Bun。当请求仅为设置、准备、打包或测试包时，验证完成后即可停止。
报告已批准的布局、Bun配置变更、包名称和版本、制品路径、执行的检查以及发布结果。仅当生成的tarball是请求的输出时才保留它们。

发布前需转换所有不符合要求的项目。所有包管理和发布命令均使用Bun执行。