GitLab NPM Package Installer

A powerful CLI tool for managing NPM packages from GitLab Package Registry with seamless local development support.

Features

• 🔍 Auto-detect GitLab packages from your dependencies
• 📦 Install packages from GitLab registry with automatic scope detection
• 🔗 Link packages for local development using file: protocol
• 🔄 Switch between local and remote packages seamlessly
• 💾 Version caching to preserve remote versions when switching
• 📊 Status tracking to see current package modes
• 🎯 Smart registry selection with version comparison support

Installation

# From npm Registry
npm install -g @microature/gitlab-installer

# From GitLab Registry (if you have gitlab-installer already)
gitlab-install add @microature/gitlab-installer -g

# Or use directly with npx
npx @microature/gitlab-installer [command]

Quick Start

Initial Setup

1. Create a .env file with your GitLab token:

GITLAB_AUTH_TOKEN=glpat-your-token-here

2. Initialize configuration:

gitlab-install init --auto-detect

This creates .gitlab-packages.json and auto-detects GitLab packages from your package.json.

Configuration

.gitlab-packages.json structure:

{
  "scopes": {
    "@your-org": "gitlab"
  },
  "packages": {
    "@your-org/package": {
      "localPath": "../local-package",
      "remoteVersion": "^1.0.0",
      "currentMode": "local"
    }
  },
  "registry": "https://gitlab.com/api/v4/packages/npm/",
  "registryPreference": {
    "strategy": "latest-version",
    "fallback": "npm-first"
  }
}

Commands

add - Install from GitLab Registry

Install packages from GitLab registry with automatic scope detection:

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

# Install dev version
gitlab-install add @your-org/package@dev

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

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

link - Link Local Development Package

Link a package to a local directory for development:

gitlab-install link @your-org/package ../local-package

This will:

• Update package.json to use file:../local-package
• Cache the current remote version
• Enable real-time changes during development

switch - Toggle Between Local and Remote

Switch packages between local development and remote registry:

# Switch to local development
gitlab-install switch @your-org/package --local

# Switch back to remote
gitlab-install switch @your-org/package --remote

# Switch all configured packages
gitlab-install switch-all --local
gitlab-install switch-all --remote

status - Check Package Status

View the current status of all configured packages:

gitlab-install status

Output:

Package Status:

🔗  @your-org/package-a
    Mode: local
    Path: ../package-a
    Current: file:../package-a
    Remote: ^1.2.3

☁️  @your-org/package-b
    Mode: remote
    Current: ^2.0.0

unlink - Remove Local Link

Unlink a package and restore the remote version:

gitlab-install unlink @your-org/package

auto-detect - Detect GitLab Packages

Automatically detect and configure GitLab packages:

# Detect with latest version strategy
gitlab-install auto-detect --strategy latest-version

init - Initialize Configuration

Initialize or update configuration:

# Basic initialization
gitlab-install init

# With auto-detection
gitlab-install init --auto-detect

setup-registry - Setup NPM Registry

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

gitlab-install setup-registry

Development Workflow

Typical Development Flow

1. Start development - Link to local package:

   gitlab-install link @your-org/package ../local-package

2. Make changes - Edit your local package, changes reflect immediately

3. Test with remote - Switch to remote version:

   gitlab-install switch @your-org/package --remote

4. Resume development - Switch back to local:

   gitlab-install switch @your-org/package --local

5. Finish development - Unlink and use remote:

   gitlab-install unlink @your-org/package

Working with Multiple Packages

Link multiple packages for development:

gitlab-install link @your-org/package-a ../package-a
gitlab-install link @your-org/package-b ../package-b
gitlab-install link @your-org/package-c ../package-c

Switch all to local/remote:

# All to local for development
gitlab-install switch-all --local

# All to remote for testing
gitlab-install switch-all --remote

Registry Selection Strategies

Configure how packages are selected when available in multiple registries:

Strategies

• npm-first - Prefer NPM registry (default)
• gitlab-first - Prefer GitLab registry
• latest-version - Choose registry with the latest version
• explicit - Use explicit scope configuration

Configuration

In .gitlab-packages.json:

{
  "registryPreference": {
    "strategy": "latest-version",
    "fallback": "npm-first"
  }
}

Preinstall Hook

Add automatic registry setup to your project:

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

This ensures GitLab packages are properly configured before npm install.

Environment Variables

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

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:

   GITLAB_AUTH_TOKEN=glpat-your-token-here

Troubleshooting

Package not found

• Ensure the package exists in GitLab registry
• Check your GitLab token has proper scopes
• Verify the package scope is configured

Link not working

• Ensure the local path exists and contains a valid package.json
• Use relative paths from your project root
• Check the linked package has been built

Switch fails

• Make sure the package was previously linked
• Verify cached remote version exists
• Run npm install after switching

Examples

Monorepo Development

Working with multiple related packages:

# Link all local packages
gitlab-install link @myorg/core ../monorepo/packages/core
gitlab-install link @myorg/utils ../monorepo/packages/utils
gitlab-install link @myorg/ui ../monorepo/packages/ui

# Development mode - all local
gitlab-install switch-all --local

# Integration testing - all remote
gitlab-install switch-all --remote

# Mixed mode - some local, some remote
gitlab-install switch @myorg/core --local
gitlab-install switch @myorg/utils --remote
gitlab-install switch @myorg/ui --local

CI/CD Integration

# .gitlab-ci.yml
before_script:
  - npm install -g @microature/gitlab-installer
  - gitlab-install init
  - npm install

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

ISC

Author

Created with ❤️ by the Microature team

For more information and updates, visit the GitLab repository.