NPM

Releases an NPM package to the public registry. Requires a package tarball generated by npm pack in the artifacts.

Configuration

Option	Description
`access`	Visibility for scoped packages: `restricted` (default) or `public`
`checkPackageName`	Package to check for current version when determining `latest` tag

Environment Variables

Name	Description
`NPM_TOKEN`	An automation token allowed to publish. Not required when using OIDC.
`NPM_BIN`	Path to npm executable. Default: `npm`
`YARN_BIN`	Path to yarn executable. Default: `yarn`
`CRAFT_NPM_USE_OTP`	If `1`, prompts for OTP (for 2FA)

Example

targets:
  - name: npm
    access: public

Workspaces Support

Craft supports automatic discovery and publishing of NPM/Yarn workspace packages. When enabled, the npm target automatically expands into multiple targets—one per workspace package—published in dependency order.

Workspace Configuration

Option	Description
`workspaces`	Enable workspace discovery. Default: `false`
`includeWorkspaces`	Regex pattern to filter which packages to include (e.g., `/^@sentry\//`)
`excludeWorkspaces`	Regex pattern to filter which packages to exclude (e.g., `/^@sentry-internal\//`)
`artifactTemplate`	Template for artifact filenames. Variables: `{{name}}`, `{{simpleName}}`, `{{version}}`

Workspace Example

targets:
  - name: npm
    access: public
    workspaces: true
    includeWorkspaces: /^@sentry\//
    excludeWorkspaces: /^@sentry-internal\//

Workspace Features

Auto-discovery: Detects packages from package.json workspaces field (npm/yarn workspaces)
Dependency ordering: Publishes packages in topological order (dependencies before dependents)
Private package filtering: Automatically excludes packages marked as private: true
Validation: Errors if public packages depend on private workspace packages
Scoped package warnings: Warns if scoped packages don’t have publishConfig.access: 'public'

Artifact Naming

By default, Craft expects artifacts named like:

@sentry/browser → sentry-browser-{version}.tgz

Use artifactTemplate for custom naming:

targets:
  - name: npm
    workspaces: true
    artifactTemplate: '{{simpleName}}-{{version}}.tgz'

OIDC Trusted Publishing

Craft supports npm’s trusted publishing (OIDC), which eliminates the need for long-lived NPM_TOKEN secrets.

Auto-detection (zero config)

If NPM_TOKEN is not set and Craft detects an OIDC-capable CI environment, it automatically uses trusted publishing:

GitHub Actions: workflow must have id-token: write permission
GitLab CI/CD: pipeline must configure id_tokens with aud: "npm:registry.npmjs.org"

Requires npm >= 11.5.1 and Node.js >= 22.14.0 (OIDC is not supported in older versions).

Explicit opt-in

Set oidc: true in .craft.yml to force OIDC mode (useful when migrating from token-based auth while both are configured):

targets:
  - name: npm
    access: public
    oidc: true

When oidc: true, Craft hard-errors if npm is too old or only yarn is available.

GitHub Actions example

permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/setup-node@v4
    with:
      node-version: '24'
      registry-url: 'https://registry.npmjs.org'
  - run: craft publish

`checkPackageName` with OIDC

The npm info command used by checkPackageName does not support OIDC — it requires traditional auth. For public packages this works without a token. For private packages, provide a read-only NPM_TOKEN; if absent, Craft will warn and skip the version check (defaulting to the latest tag).

Notes

The npm utility must be installed on the system
If npm is not found, Craft falls back to yarn publish (only in non-OIDC mode)
For scoped packages (@org/package), set access: public to publish publicly
Pre-release versions are automatically tagged as next instead of latest

NPM