@glpkg/installer

A CLI tool for installing and managing NPM packages from GitLab Package Registry.

Installation

# From npm Registry
npm install -g @glpkg/installer

# Or use directly with npx
npx @glpkg/installer [command]

Quick Start

Initial Setup

Create a .env file with your GitLab token:

GITLAB_AUTH_TOKEN=glpat-your-token-here

Token Setup

1. Go to GitLab → Settings → Access Tokens
2. Create a token with read_api and read_registry scopes
3. Add to .env file in your project root

Usage

Usage: gitlab-install [options] [command]

Install packages from GitLab NPM registry

Options:
  -V, --version                   output the version number
  -h, --help                      display help for command

Commands:
  add [options] <packages...>     Add GitLab packages (use @version syntax like npm)
  setup-registry                  Setup .npmrc for GitLab packages (used by preinstall hook)
  update [options] [packages...]  Update GitLab packages to their latest versions
  help [command]                  display help for command

Commands

add - Install GitLab Packages

Usage: gitlab-install add [options] <packages...>

Add GitLab packages (use @version syntax like npm)

Options:
  -D, --save-dev  Install as devDependencies
  -g, --global    Install packages globally
  -h, --help      display help for command

Examples:

# Install specific version
gitlab-install add @glpkg/[email protected]

# Install dev version
gitlab-install add @glpkg/package@dev

# Install as devDependency
gitlab-install add @glpkg/package -D

# Install globally (for CLI tools)
gitlab-install add @glpkg/cli-tool -g

update - Update GitLab Packages

Usage: gitlab-install update [options] [packages...]

Update GitLab packages to their latest versions

Options:
  -g, --global  Update packages globally
  -h, --help    display help for command

Examples:

# Update all GitLab packages
gitlab-install update

# Update specific packages
gitlab-install update @glpkg/package

# Update multiple packages
gitlab-install update @glpkg/pkg1 @glpkg/pkg2

# Update global packages
gitlab-install update -g

setup-registry - Setup NPM Registry

Setup .npmrc for GitLab packages (used by preinstall hook):

gitlab-install setup-registry

This command is typically used in the preinstall hook of your package.json:

{
  "scripts": {
    "preinstall": "gitlab-install setup-registry"
  }
}

Configuration

The tool creates a .gitlab-packages.json file to track configured GitLab scopes:

{
  "scopes": ["@glpkg", "@your-org"],
  "registry": "https://gitlab.com/api/v4/packages/npm/"
}

This file is automatically managed by the tool when you add packages.

How It Works

1. When you install a package, the tool:

   • Detects the package scope (e.g., @glpkg)
   • Temporarily configures .npmrc to use GitLab registry for that scope
   • Adds authentication token
   • Runs npm install
   • Restores original .npmrc

2. The configuration is saved to .gitlab-packages.json for future use

3. The setup-registry command can be used in preinstall hooks to automatically configure the registry before regular npm install

Environment Variables

• GITLAB_AUTH_TOKEN - Your GitLab personal access token (required)
• GITLAB_REGISTRY - Override default GitLab registry URL (optional)

Troubleshooting

Package not found

• Ensure the package exists in GitLab registry
• Check your GitLab token has proper scopes (read_api, read_registry)
• Verify the token is correctly set in .env file

Authentication errors

• Make sure your token hasn't expired
• Verify the token has the required permissions
• Check that the .env file is in your project root

License

ISC

Author

Created with ❤️ by the Microature team