To share your code with a limited set of users or teams, you can publish private user-scoped or organization-scoped packages to the npm registry.

For more information on scopes and private packages, see "About scopes" and "About private packages".

Creating a private package

1. If you are using npmrc to manage accounts on multiple registries, on the command line, switch to the appropriate profile:

   npmrc <profile-name>

2. On the command line, create a directory for your package:

   mkdir my-test-package

3. Navigate to the root directory of your package:

   cd my-test-package

4. If you are using git to manage your package code, in the package root directory, run the following commands, replacing git-remote-url with the git remote URL for your package:

   git init
   git remote add origin git://git-remote-url

5. In the package root directory, run the npm init command and pass the scope to the scope flag:

   • For an organization-scoped package, replace my-org with the name of your organization:

     npm init --scope=@my-org

   • For a user-scoped package, replace my-username with your username:

     npm init --scope=@my-username

6. Respond to the prompts to generate a package.json file. For help naming your package, see "Package name guidelines".

7. Create a README file that explains what your package code is and how to use it.

8. In your preferred text editor, write the code for your package.

Reviewing package contents for sensitive or unnecessary information

Publishing sensitive information to the registry can harm your users, compromise your development infrastructure, be expensive to fix, and put you at risk of legal action. We strongly recommend removing sensitive information, such as private keys, passwords, personally identifiable information (PII), and credit card data before publishing your package to the registry. Even if your package is private, sensitive information can be exposed if the package is made public or downloaded to a computer that can be accessed by more users than intended.

For less sensitive information, such as testing data, use a .npmignore or .gitignore file to prevent publishing to the registry. For more information, see this article.

Testing your package

To reduce the chances of publishing bugs, we recommend testing your package before publishing it to the npm registry. To test your package, run npm install with the full path to your package directory:

Publishing private packages

By default, scoped packages are published with private visibility.

There are two ways to publish your package to the npm registry:

1. Direct publishing
2. Staged publishing

Direct publishing

To publish directly with npm publish, you need either:

• Two-factor authentication (2FA) enabled on your account, or
• A granular access token (GAT) with bypass 2FA enabled

For more information, see the npm documentation on requiring 2FA for package publishing.

1. On the command line, navigate to the root directory of your package.

   cd /path/to/package

2. To publish your private package to the npm registry, run:

   npm publish

3. To see your private package page, visit https://npmjs.com/package/*package-name*, replacing *package-name* with the name of your package. Private packages will say private below the package name on the npm website.

   

For more information on the publish command, see the CLI documentation.

Staged publishing

Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package is published to the registry, a maintainer must review and approve it with 2FA.

A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.

1. On the command line, navigate to the root directory of your package.

   cd /path/to/package

2. To stage your package, run:

   npm stage publish

   This submits your package to a staging area.

3. To check that your package has been staged, use either of the following methods:

   • In the CLI, run npm stage list <package-name> to find the staged package and its stage ID.
   • On npmjs.com, open the Staged Packages tab to review staged packages.

4. To approve and publish the staged package, use one of the following methods:

   • In the CLI, run the npm stage approve <stage-id> command.
   • On npmjs.com, review the staged package in the Staged Packages tab, then click Approve.

   Note: You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on npmjs.com. Once approved, the package is published to the live registry.

For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see Staged publishing.

Edit this page on GitHub

6 contributorskarenjlishmamdependabot[bot]lukekarrysericmuttaethomson

Last edited by karenjli on May 20, 2026