Configuring NPM for use with GitHub Package Registry

You can configure npm to publish packages to GitHub Package Registry and to use packages stored on GitHub Package Registry as dependencies in an npm project.

GitHub Package Registry is currently available in limited public beta. For more information, see "About GitHub Package Registry."

In this article

Authenticating to GitHub Package Registry

You must use a personal access token with the read:packages and write:packages scopes to publish and delete public packages in the GitHub Package Registry with npm. Your personal access token must also have the repo scope when the repository is private. For more information, see "Creating a personal access token for the command line."

You can configure npm to use your token when pushing new packages by editing your ~/.npmrc file or creating one if it doesn't exist. It should look similar to the example below.

//npm.pkg.github.com/:_authToken=PERSONAL-ACCESS-TOKEN

You can also login with npm using your username and personal access token. Replace the OWNER in the scope parameter with the GitHub user or organization name that contains the repository where you will publish the package.

$ npm login --registry=https://npm.pkg.github.com --scope=@OWNER
> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC EMAIL ADDRESS

Publishing a package

You can set up the scope mapping for your project using either a local .npmrc file in the project or using the publishConfig option in the package.json.

Note: GitHub Package Registry only supports scoped NPM packages. Scoped packages have names with the format of @owner/name. Scoped packages always begin with an @ symbol. You may need to update the name in your package.json to use the scoped name. For example, "name": "@codertocat/hello-world-npm".

Because npm does not support uppercase letters, you must use lowercase letters for the name field even if your GitHub user or organization name contains uppercase letters.

For more information, see "npm-scope" in the npm documentation.

Configuring a package scope using a local .npmrc

Using a .npmrc can help ensure that other developers who publish the package won't accidentally publish it to npmjs.org.

  1. In your project directory, create or edit your .npmrc file to contain the line below. Replace OWNER with the GitHub user or organization name that contains the repository where you will publish the package.

    @OWNER:registry=https://npm.pkg.github.com/
    
  2. Check the local .npmrc into your Git repository.

  3. Verify the name of your package in your project's package.json. The name field must contain the scope and the name of the package. For example, if your package is called "test", and you are publishing to the "My-org" GitHub organization, the name field in your package.json should be @my-org/test. Because npm does not support uppercase letters, you must use lowercase letters for the name field even if your GitHub user or organization name contains uppercase letters.

  4. Verify the repository field in your project's package.json. The repository field must match the URL for your GitHub repository. For example, if your repository URL is github.com/my-org/test then the repository field should be git://github.com/my-org/test.git.

  5. Publish the package:

    $ npm publish
  6. You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

    https://github.com/OWNER/REPOSITORY/packages
    

Configuring a package scope using publishConfig in package.json

You can set the registry that a package should be published to by using the publishConfig element in the package.json file. For more information, see "publishConfig" in the npm documentation.

  1. Edit the package.json file for your package and include a publishConfig entry.

      "publishConfig": {
        "registry":"https://npm.pkg.github.com/"
      },
    
  2. Verify the repository field in your project's package.json. The repository field must match the URL for your GitHub repository. For example, if your repository URL is github.com/my-org/test then the repository field should be git://github.com/my-org/test.git.

  3. Publish the package:

    $ npm publish
  4. You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

    https://github.com/OWNER/REPOSITORY/packages
    

Publishing multiple packages to the same GitHub repository

When you publish a package, by default GitHub Package Registry uses the package name to determine the GitHub repository where it will be published. For example, a package named @my-org/test would be published to the my-org/test GitHub repository. A GitHub release and associated Git tag will be automatically created for the version of the package, if it doesn't already exist.

If you would like to publish multiple packages to the same repository, you can include the URL to the GitHub repository in the repository field of the package.json. GitHub will match the repository based on that field, instead of based on the package name.

"repository" : {
    "type" : "git",
    "url": "ssh://git@github.com/OWNER/REPOSITORY.git"
  },

For more information on creating your package, see "How to create Node.js Modules" in the npm documentation.

Receiving package registry events

You can receive webhook events when a package is published or updated. For more information, see "RegistryPackageEvent" in the GitHub Developer documentation.

Installing a package

Using packages from GitHub in your projects is similar to using packages from npmjs.com. Add your package dependencies to your package.json specifying the full scoped package name.

Because npm does not support uppercase letters, you must use lowercase letters for the name field even if your GitHub user or organization name contains uppercase letters.

  1. Authenticate to GitHub Package Registry using either a .npmrc file or with npm login. For more information, see "Authenticating to GitHub Package Registry."

  2. We recommend creating a local .npmrc in the project that establishes the scope mapping. This will ensure other developers on your project who run npm install will get dependencies from your GitHub repository, as opposed to npmjs.org. Add a line to .npmrc replacing OWNER with the GitHub user or organization name that contains the repository for the package you are installing.

    @OWNER:registry=https://npm.pkg.github.com/
    
  3. Check the local .npmrc file into your Git repository.

  4. Configure package.json to use the package. For example, this package.json uses the @octo-org/octo-app package as a dependency.

    {
      "name": "@my-org/server",
      "version": "1.0.0",
      "description": "Server app that uses the @octo-org/octo-app package",
      "main": "index.js",
      "author": "",
      "license": "MIT",
      "dependencies": {
        "@octo-org/octo-app": "1.0.0"
      }
    }
    
  5. Install the package.

    $ npm install

For more information on using a package.json in your project, see "Working with package.json" in the npm documentation.

Deleting a package

To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support package deletion or deleting a version of a package. Under special circumstances, such as for legal reasons or to conform with GDPR standards, you can request deleting a package through GitHub Support. Contact GitHub Support using our contact form and the subject line "GitHub Package Registry."

Ask a human

Can't find what you're looking for?

Contact us