Workspaces & Publishing

A workspace is declared in the root package.json through the workspaces array, with folder paths or globs. The root of a monorepo is usually "private": true, which makes npm refuse to publish it.

The library has its own package.json, with the fields that make it publishable (they are explained in What publishing adds for Node packages), and the application depends on it with an ordinary version range.

The first line of npm ls output, which prints the absolute path of the root, was omitted. The same result was obtained on Node.js 26 with npm 11.19.1, on Node.js 24 with npm 11.19.0 and on Node.js 22 with npm 10.9.9. The @bookshelf/cli workspace is satisfied by the local @bookshelf/core (deduped), not by a copy from the registry, because the range ^1.0.0 matches the local version.

Source: npm Docs: Workspaces

Almost every npm command accepts the workspace (short -w) and workspaces configuration options. --workspace selects one or more workspaces by name, by path, or by the path of a parent folder, and may be repeated; --workspaces selects all of them. Commands that work on the node_modules tree (install, update) link workspaces by default, while commands that do something else (test, exec, publish) operate on the root project unless workspaces are selected.

The first command ran only the test script of @bookshelf/core. The second printed nothing and exited with code 0, because --if-present makes npm skip the workspaces that do not define the script. The third failed on the first workspace without a build script. On Node.js 22 the node:test reporter prints # pass 1 where Node.js 26 and 24 print ℹ pass 1; that is the test runner, not npm.

Source: npm Docs: Workspaces

Dependencies are added to one workspace with the same option. npm hoists the package to the root node_modules when there is no conflict, and writes the range in the workspace’s own package.json.

The package.json of @bookshelf/core gained "abbrev": "^5.0.0" under dependencies, and the package was installed in the root node_modules (the ls shows it there, and there is no packages/core/node_modules). The tree shows the version that resolved on 2026-10-03; use any small package you like. The same command was run on Node.js 24 and 22 with the same layout.

Source: npm Docs: Workspaces

Source: npm Docs: npm link (configuration)

The documented spelling is --workspaces. The short form -ws was tolerated with a warning in npm 11.19.1 (measured below) and is rejected in npm 12: the changelog of npm 12.0.0 (2026-07-08) says that unknown flags, abbreviated flags and single-hyphen multi-character shorthands now throw instead of warning. Scripts and CI files that still use -ws must be updated before the npm bundled with a Node.js line moves to npm 12.

On npm 12.2.0 the same command exits with -ws is not a valid single-hyphen cli flag. Did you mean --ws?. That message shows that --ws is accepted (running npm run test --ws --if-present worked on both versions), but only --workspaces is documented, so use that one. npm 12.0.0 also declares the Node.js versions it supports: ^22.22.2 || ^24.15.0 || >=26.0.0.

Source: npm Docs: Changelog

Two details separate npm from the other package managers. First, npm writes an ordinary range (^1.0.0) for a workspace dependency, and resolves it to the local workspace as long as the version satisfies it; npm does not support the workspace: protocol that pnpm and Yarn use (see pnpm and Yarn as alternatives). A package.json that contains "@bookshelf/core": "workspace:^" fails npm install with EUNSUPPORTEDPROTOCOL (measured on npm 11.19.1 and 10.9.9), which matters when you move a repository between package managers.

Second, because Node.js resolves the symlink to its real path, a workspace is not under node_modules from the runtime’s point of view. That is why a workspace can export a .ts file and a sibling can import it with type stripping, while the same file installed from a tarball cannot be loaded (see Publishing a TypeScript package). It also means that peer dependencies of a linked package are looked up from its real location, the problem described under --preserve-symlinks in the CLI documentation.

Source: Node.js API: Command-line options (--preserve-symlinks)

npm publish --workspace=<name> publishes one workspace and npm publish --workspaces publishes all of them. A workspace marked "private": true is skipped, as the dry run in the next section shows. Workspaces give you one lockfile (package-lock.json at the root), one install and linked packages, but no task graph: npm does not compute a build order or cache results, and it runs scripts in the order of the workspaces array. If a package must be built before another, order the array accordingly or write the order in a root script. npm pack can also select a workspace through configuration since npm 12.1.0.

Source: npm Docs: npm publish

Corepack, the tool that created pnpm and yarn shims and pinned the version in the packageManager field, was distributed with Node.js from version 14.19.0 up to, but not including, 25.0.0, according to the Corepack project. Node.js 25.0.0 (2025-10-15) stopped distributing it, and the Corepack page of the Node.js API documentation now redirects to the Corepack repository. The Node.js 24 documentation already marked Corepack as Stability 1 Experimental and announced that it would no longer be distributed from v25. In practice, on 2026-10-03: corepack is not found on Node.js 26.10.0, while versions 24.21.0 and 22.23.3 still have it. See Corepack, pnpm and Yarn for the install options in detail. Corepack still exists as a separate project (npm install --global corepack), and the Yarn installation page continues to start with that step; this page does not depend on it. The options that work the same on every line are:

The examples below used the first option inside a scratch folder, with pnpm 12.9.1 and Yarn 4.18.1, and ran on Node.js 26, 24 and 22.

The Scope: line shows that pnpm -r ran in 2 of the 3 projects and skipped the root, and the output was filtered. The bookshelf binary is not linked into the @bookshelf/cli workspace itself, so the command runs the script with node.

Source: pnpm: Workspace

The test output was filtered to the summary lines.

nodeLinker: node-modules was set because Yarn 4 uses Plug’n’Play by default, which does not create a node_modules folder and needs the tools around it to be PnP-aware. Yarn 4 also has an experimental nodeExperimentalPackageMap setting that works with Node.js package maps (--experimental-package-map, Stability 1 Experimental, added in v26.4.0).

Source: Yarn: Workspaces, Yarn: .yarnrc.yml

npm pack --dry-run lists the files that would go into the tarball without writing it, and npm publish --dry-run runs everything except the upload. The npm documentation recommends npm pack --dry-run to see what is included. Neither command publishes anything, which makes them safe in a scratch folder or CI job.

The test folder is not in the list because of "files": ["src"], while package.json, README.md and LICENSE are always included. The shasum and integrity lines were omitted. The output was identical on Node.js 26, 24 and 22.

Source: npm Docs: npm pack

Run from the root, npm publish --dry-run --workspaces printed Skipping workspace @bookshelf/cli, marked as private and then the report of @bookshelf/core. On npm 10.9.9 (Node.js 22) the warning reads npm warn This command requires you to be logged in…​ without the publish word. The output of the machine-readable form changed in npm 12.0.0, whose changelog says that the --json output of npm pack and npm publish is now always consistent and in the same format: on npm 11.19.1, npm pack --dry-run --json prints an array with one object per package, and on npm 12.2.0 it prints an object keyed by package name. Scripts that parse that JSON need to handle both.

Source: npm Docs: npm publish

The dry run shows the files, not whether the package works. The reliable check is to pack a real tarball into a scratch folder, install it in a throw-away project and import it, the way a consumer would. Packing is local and does not publish.

The package entry point works, the private src/index.js path is rejected by exports, and require() of an ESM-only package works because the package has no top-level await. That last result was measured on Node.js 26, 24 and 22.23.3, and it is why the library can be ESM-only and set "engines": { "node": ">=22.12" }: require(esm) is unflagged from v22.12.0 and v20.19.0 and Stable since v25.4.0. The Node.js Learn article on publishing a package was written for older lines (it says that requiring ESM works on "22.x and 23.x" and uses >=12.22.7 in its engines examples); its advice to publish one format only and to describe the entry points in exports still holds, and the dual-package decisions are explained in package.json, exports & imports and ESM & CommonJS Interop.

Source: Node.js Learn: Publishing a package

engines is advisory unless the installing project sets engine-strict. A package that requires a newer Node.js than the current one installs with a warning by default and fails with --engine-strict.

Both commands behave the same on Node.js 22 with npm 10.9.9. Declare the range you actually test, and use a lower bound that matches the oldest maintained line you support, today >=22.12 for ESM-only packages that must be required from CommonJS. Node.js 22 reaches end of life on 2027-04-30.

Source: npm Docs: package.json (engines)

Node.js 22.18.0 and later run .ts files directly, which makes TypeScript convenient for applications. For a package that other projects install, the guidance in the Learn article is the opposite: publish JavaScript and declaration files. The fields that point at published content (exports, main) must name the compiled .js files, while scripts that run on the source (test) name the .ts files, and Node.js refuses to strip types inside node_modules, so a package that ships raw TypeScript cannot be loaded.

That failure was measured on Node.js 26, 24 and 22 (npm pack in a folder whose package.json has "exports": "./index.ts", then npm install of the tarball, then import 'raw-ts'). When the same package was installed as a link (npm install ../pkg, which creates a symlink), the file loaded, because the real path is outside node_modules: the behaviour that makes .ts workspaces convenient is also why you cannot judge a TypeScript package from a link.

Source: Node.js API: Modules: TypeScript (type stripping in dependencies)

The recipe below follows the Learn article: compile in prepack, publish dist/ with its .d.ts files, and add a types condition first in exports.

rewriteRelativeImportExtensions turns the ./normalize.ts import written in the source into ./normalize.js in the output, and erasableSyntaxOnly (TypeScript 5.8 and later) makes the compiler reject syntax that type stripping cannot run, such as enums and namespaces. The source files use the .ts extension in their imports, as Node.js requires when it runs them directly.

This was run with TypeScript 7.0.2 (the version npm resolved on 2026-10-03) on Node.js 26, 24 and 22. npm pack --dry-run ran prepack, so it created dist/ in the working folder; npm publish runs it too, which is what you want. The Learn article warns that node --run does not run the pre and post scripts, so do not use it for the packing step. The test files are excluded by the files allow-list and by the exclude setting. The details of the compiler options are in tsconfig and Compiler Options, and the runtime side of TypeScript is in TypeScript in Node.js.

Source: Node.js Learn: Publishing a TypeScript package, Node.js API: Modules: TypeScript

Provenance has two parts. The provenance attestation links the package to its source and build instructions, and is built from the identity token of the CI run. The publish attestation is generated by the registry when an authorised user publishes. Both are signed with Sigstore and logged in a public transparency ledger. In a GitHub Actions job it takes the id-token: write permission and the --provenance flag:

Setting NPM_CONFIG_PROVENANCE=true, an entry provenance=true in .npmrc, or "publishConfig": { "provenance": true } in package.json has the same effect for tools that do not call npm publish directly. The option is documented in the npm publish page, where the provenance-file option takes precedence over automatic generation (a fix in npm 12.1.0 made that the case for trusted publishing too). Consumers check attestations with npm audit signatures. Outside a supported CI provider there is nothing to attest, so provenance is a CI feature; this page does not run it. The --dry-run publish on a laptop above printed no provenance output.

Source: npm Docs: Generating provenance statements

Trusted publishing replaces the stored token with a trust relationship configured on the package: you tell npm which repository, which workflow file and, optionally, which environment may publish it. At publish time the CI provider issues a short-lived OIDC token for that workflow, the npm CLI detects the environment automatically and uses the token before falling back to other credentials, and no secret has to be created, rotated or hidden from logs. This implements the trusted publishers standard of the Open Source Security Foundation, as in other registries. npm announced it as generally available on 2025-07-31; with trusted publishing, provenance attestations are generated without the --provenance flag.

The relationship is configured on npmjs.com, in the package settings, or with the npm trust command (added in npm 11.10.0; it requires npm 11.15.0 or later according to its documentation, an account with 2FA enabled, and a package that already exists). For GitHub Actions the settings are the organisation or user, the repository, the workflow filename (only the file name, with .yml or .yaml, in .github/workflows/), an optional environment, and the allowed actions. Those allowed actions are tied to staged publishing: npm stage publish is always allowed, and the relationship can also allow a direct npm publish and npm dist-tag (OIDC authentication for dist-tag arrived in npm 12.2.0). Configurations created before 2026-05-20 allow only npm publish; the dates are described on the npm page.

On Node.js 26 (npm 11.19.1) and Node.js 24 (npm 11.19.0) the command exists. On Node.js 22.23.3, which bundles npm 10.9.9, it prints Unknown command: "trust", and npm stage is unknown too. That is the practical effect of bundling: a pipeline that runs on Node.js 22 must upgrade npm (npm install --global npm@latest) before it can use trusted or staged publishing, while the 24 and 26 lines already include a sufficient npm.

Source: npm Docs: npm trust

The workflow that publishes is an ordinary one with two requirements: the id-token: write permission, and a GitHub-hosted runner. It contains no token or secret. It follows the example in the npm documentation.

The workflow does not set NODE_AUTH_TOKEN: with trusted publishing the CLI exchanges the OIDC token itself. The actions/checkout@v6 and actions/setup-node@v6 major versions are those shown in the npm documentation on 2026-10-03; pin or update them according to your own policy. Because the install step is npm ci, the lockfile decides what runs in the release job, which is the point of release builds.

Source: npm Docs: Trusted publishing

Trusted publishing removes the token, and with it the human who used to type a one-time password. Staged publishing puts a human back in the loop without putting a secret back in the pipeline. The pipeline runs npm stage publish (no 2FA prompt, usable with any token type), and the package waits in a staging area. A maintainer then reviews it and approves it with 2FA, either on npmjs.com in the Staged Packages tab or with the CLI.

Staged versions share the version uniqueness of published ones, so a version that is staged cannot be published again; several versions of the same package can be staged; and the dist-tag is fixed when staging (to change it you reject and stage again). When the package does not exist yet, the npm page says that npm publishes a placeholder version 0.0.0-stage, with the staged contents hidden until approval. The documentation itself notes that staged publishing by itself does not make an account or an organisation more secure; the best practices still apply.

This was run on Node.js 26 (npm 11.19.1) and, as above, does not exist on Node.js 22’s npm. The (dry-run) markers show that nothing was uploaded. Staged-package status display (npm stage) and read-write-stage-only granular tokens arrived in npm 12.1.0.

Source: npm Docs: Staged publishing, npm Docs: npm stage

Source: npm Docs: About access tokens, npm Docs: Trusted publishing for npm packages, GitHub Changelog: npm classic tokens revoked (dates, session tokens, 90-day limit)