Imagine you are a head chef. To ensure all your chain restaurants produce the same delicious dishes, you’ve developed a series of “secret sauces.” You want these sauces sent to each branch, but you can’t have random passersby taking them.

In the world of software development, these secret sauces are company-internal “private packages.”

As projects grow, you’ve likely encountered this frustration: duplicating the same UI component or utility function across every project, or struggling with Git Submodules until you question your life choices. In fact, all you need is a “Private Pantry (Private NPM Registry).” Today, we’ll discuss how to use pnpm to publish packages to GitLab, so team members can install them just like open-source packages with a single command.

Why Do You Need Private Packages and Scopes?

In the Node.js universe, private packages must have a “surname”—this is the Scope.

For example, if your company is named @my-company, your package name might look like this: @my-company/ui-kit. With this surname, when pnpm sees it, it won’t aimlessly search npmjs.org. Instead, it will head straight to your specified company coordination points.

Key Decision: Group Level vs. Project Level

In GitLab, this is like deciding where to store your seasonings:

Setting Up the “Passport”: Access Tokens and Environment Variables

To enter the underground granary, you first need to obtain an “access card.”

1. Go to GitLab’s Settings > Access Tokens.
2. Apply for a Token, checking the read_api (for downloading) and write_package_registry (for publishing) permissions.
3. Important: Once you have the Token, never hardcode it directly into your code or .npmrc file! That’s like leaving the vault key in the door.

The most professional approach is to hide it in “environment variables.” Add this line to your Mac or Linux terminal (e.g., ~/.zshrc):

export GITLAB_TOKEN="your_GitLab_Token"

This way, the system will automatically attach the credentials for you, making it both secure and convenient.

Navigation Settings: The Essence of .npmrc

Next, we’ll create a navigation map, .npmrc, in the project root to tell pnpm where to go:

# For anything starting with @my-company, go to GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# Set up access card authentication (reading the environment variable we just set)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

Just swap in your company’s Group ID, and the road is paved!

The Final Mile Before Publishing: The Art of Packaging

Many people rush to publish after setting up the connection, only to accidentally upload test files or even secret configurations. This is where the files field in package.json comes in handy.

This is an “allowlist” concept:

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

Before publishing, it’s recommended to use the pnpm pack command to unbox and check the content locally. Once everything looks good, confidently run pnpm publish!

Conclusion

Building a private pantry isn’t difficult. The keys are:

1. Apply for a Token and protect it with environment variables.
2. Configure the correct .npmrc navigation map.
3. Use the files field in package.json for precise shipping.

By mastering this workflow, you can make your company’s code reuse professional, secure, and elegant. Now, go build your own central kitchen!

Reference

• package.json | npm Docs
• Package registry | GitLab Docs