npm-publish

Publish the current package to the default npm registry

$ npm publish

$ npm publish [path/to/package_directory]

$ npm publish --access public

$ npm publish --access restricted

$ npm publish --registry [https://registry.npmjs.org/]

$ npm publish --dry-run

$ npm publish --tag [beta]

$ npm publish --otp [one_time_password]

npm publish [<folder>|<tarball>] [--tag <tag>] [--access <public|restricted>] [--otp <otpcode>] [--dry-run] [--registry <url>] [--workspace <workspace_name>] [--workspaces]

--tag
    Registers the published package with the given tag. This can be used to provide an alias for the package version, such as `beta` or `next`, instead of the default `latest`.

--access
    Controls the visibility of scoped packages. Scoped packages default to `restricted` (private) access, requiring this option to be `public` for free open-source publishing. Unscoped packages are always `public`.

--otp
    Provides a one-time password for two-factor authentication, if required by the npm registry.

--registry
    Specifies a custom registry URL to publish the package to, overriding the default configured registry.

--dry-run
    Performs all publishing steps except the actual upload to the registry. Useful for previewing what files will be included and what scripts will run without making permanent changes.

--workspace
    Publishes a package from a specific workspace within a monorepo setup.

--workspaces
    Publishes all packages from all defined workspaces in the current project.

--if-present
    Used with `--workspaces`, it will only run `publish` for workspaces that are present in the `workspaces` array.

--provenance
    Adds provenance information to the package metadata, linking the build and publishing process to its source.

--no-git-checks
    Bypasses the checks that ensure your package repository is clean and on the main branch before publishing. Use with caution.

--ignore-scripts
    Prevents the execution of `prepublish`, `prepare`, `prepublishOnly`, and `postpublish` lifecycle scripts during the publish process.

The `npm publish` command uploads a package to the npm registry, making it available for others to install. It works by taking the current directory (or a specified folder/tarball) and packaging its contents according to the `package.json` specification. Before publishing, `npm publish` performs several checks, including validating the `package.json`, ensuring the package name and version are unique (or scoped), and respecting `.npmignore` and `.gitignore` files to exclude unnecessary files. It compresses the package into a tarball and then uploads it to the configured npm registry. This command is fundamental for sharing reusable JavaScript modules and applications within the Node.js ecosystem. It supports various options to control access, associate tags (like `latest` or `beta`), specify a different registry, and manage two-factor authentication requirements. It's crucial to ensure your `package.json` correctly defines your package's metadata and files to be included.

Authentication Required: You must be logged in to npm (`npm login`) with credentials that have publishing rights to the package or scope.
Version Uniqueness: Each version of a package must be unique on the registry. Attempting to publish an existing version will result in an error.
Scoped Package Access: Scoped packages (`@scope/package-name`) default to `restricted` access. To publish them publicly, you must explicitly use `--access public`.
Immutable After 72 Hours: Published packages are generally considered immutable. Unpublishing is highly discouraged and only possible within 72 hours of publication, and only if no other packages depend on it.
Sensitive Information: Ensure no sensitive information (e.g., API keys, private configuration) is included in your package. Use `.npmignore` or the `files` array in `package.json` to control what gets published.
Git State: By default, `npm publish` will warn or error if your working directory is not clean or if you are not on the main branch. This can be overridden with `--no-git-checks`, but is not recommended.

The files included in your published package are determined by the `files` array in your `package.json` and `.npmignore` (or `.gitignore`).
The `files` array explicitly lists files or directories to include. If `files` is not specified, `npm publish` will include all files not ignored by `.npmignore` or `.gitignore`. A `.npmignore` file works similarly to `.gitignore` but is specific to npm, taking precedence over `.gitignore` for published content. It's crucial to properly configure these to avoid publishing sensitive data or unnecessary large files.

`npm publish` triggers several lifecycle scripts defined in `package.json`. These include:
• prepublish: (deprecated, superseded by `prepare` and `prepublishOnly`) Runs before the package is packed and published.
• prepare: Runs before the package is packed, regardless of whether it's for `publish`, `install`, or `pack`. Ideal for transpilation or build steps.
• prepublishOnly: Runs only before `npm publish`. Good for final checks or builds specifically for publishing.
• postpublish: Runs after the package has been successfully published. Useful for cleanup or notification.
Understanding these scripts is vital for managing your package's build and deployment process correctly.

By default, `npm publish` sets the `--tag` to `latest`. This means `npm install ` will install the version published with the `latest` tag. You can publish a new version with a different tag (e.g., `npm publish --tag beta`) and later promote it to `latest` using `npm dist-tag add @ latest`. This allows for managing different release channels (e.g., stable, beta, alpha) for your package.

The `npm publish` command has been a core component of the Node Package Manager since its early days, facilitating the sharing and reuse of JavaScript modules. Its functionality has evolved significantly to accommodate the growing npm ecosystem. Key developments include the introduction of scoped packages in npm version 2, allowing for namespaced packages (e.g., `@scope/package`), and the subsequent addition of the `--access` option to manage their public/restricted visibility. Support for two-factor authentication (`--otp`) was integrated to enhance security for publishers. More recently, features like workspaces (introduced in npm 7) streamlined the publishing of multiple interdependent packages from monorepos, and the `--provenance` flag was added to provide verifiable supply chain information, reflecting ongoing efforts to improve security and transparency in package distribution.

npm login(1), npm logout(1), npm install(1), npm pack(1), npm version(1), npm owner(1), npm unpublish(1), npm view(1), npm config(1), npm access(1)