Publish private NPM package to Gitlab

Introduction

This tutorial will guide you through the process of publishing a private NPM package to GitLab. By the end of this guide, you'll understand how to set up your Node package, update it for GitLab, configure your GitLab token, and utilize the package from the GitLab registry. This is particularly useful for developers looking to manage their packages securely within their GitLab projects.

Step 1: Set Up and Test Node Package Locally

1. Create a new directory for your package:

   • Open your terminal and run:

     mkdir my-package
     cd my-package
     

2. Initialize the Node package:

   • Use the following command to create a package.json file:

     npm init -y
     

3. Create an index file:

   • Create a file named index.js in your package directory:

     touch index.js
     

   • Add some sample code to index.js. For example:

     module.exports = () => {
         console.log("Hello from my package!");
     };
     

4. Test your package locally:

   • Within the package directory, run:

     node index.js
     

   • Ensure it outputs "Hello from my package!".

Step 2: Update Package for GitLab

1. Modify package.json for GitLab:

   • Open package.json and add the following fields:

     {
         "name": "@your-username/my-package",
         "version": "1.0.0",
         "publishConfig": {
             "registry": "https://gitlab.com/api/v4/packages/npm/"
         }
     }
     

   • Replace your-username with your GitLab username.

2. Add a .gitignore file (optional):

   • Create a .gitignore file to exclude unnecessary files:

     touch .gitignore
     

   • Add node_modules and dist to the .gitignore file.

Step 3: Set Up GitLab Token

1. Create a personal access token in GitLab:

   • Go to GitLab and navigate to User Settings > Access Tokens.
   • Name your token, select the read_api and write_api scopes, and create the token.

2. Set the GitLab token in your environment:

   • In your terminal, run:

     export NPM_TOKEN=your_personal_access_token
     

   • Replace your_personal_access_token with the token you just created.

Step 4: Publish Package to GitLab

1. Login to GitLab NPM registry:

   • Use the following command to authenticate:

     npm login --scope=@your-username --registry=https://gitlab.com/api/v4/packages/npm/
     

   • Enter your GitLab username and the token as the password.

2. Publish your package:

   • Run the command:

     npm publish
     

Step 5: Using Package from GitLab Registry

1. Install your package in another project:

   • In your project directory, run:

     npm install @your-username/my-package --registry=https://gitlab.com/api/v4/packages/npm/
     

2. Import and use your package:

   • In your project, you can now use it like this:

     const myPackage = require('@your-username/my-package');
     myPackage(); // Outputs: Hello from my package!
     

Conclusion

You have successfully published a private NPM package to GitLab and learned how to use it in your projects. Key takeaways include setting up your package correctly, configuring GitLab tokens, and managing your packages securely. For further exploration, consider looking into more advanced CI/CD integrations with GitLab for automated deployments and package management.