npm Registry Guide

Artifact Keeper provides a fully compatible npm registry for publishing and installing JavaScript and TypeScript packages.

Endpoint

All npm operations use the /npm endpoint:

http://localhost:8080/npm/

Configuration

.npmrc Configuration

Create or edit .npmrc in your project root or home directory (~/.npmrc):

registry=http://localhost:8080/npm/

Authentication

Option 1: npm login

Interactive login:

npm login --registry=http://localhost:8080/npm/

Enter your Artifact Keeper username and password when prompted.

Option 2: Auth Token

Add authentication token directly to .npmrc:

registry=http://localhost:8080/npm/
//localhost:8080/npm/:_authToken=your-auth-token

Option 3: Basic Auth

Use base64-encoded credentials:

registry=http://localhost:8080/npm/
//localhost:8080/npm/:_auth=base64(username:password)
//localhost:8080/npm/:always-auth=true

Publishing Packages

Prepare Your Package

Ensure package.json is properly configured:

{
  "name": "my-package",
  "version": "1.0.0",
  "description": "My awesome package",
  "main": "index.js",
  "author": "Your Name",
  "license": "MIT"
}

Publish to Registry

npm publish

Publish Scoped Package

For organization or user-scoped packages:

{
  "name": "@mycompany/my-package",
  "version": "1.0.0"
}

Configure scope registry:

@mycompany:registry=http://localhost:8080/npm/
//localhost:8080/npm/:_authToken=your-auth-token

Publish:

npm publish --access public

Or for private packages:

npm publish --access restricted

Publish Specific Tag

Publish with a custom tag (default is latest):

npm publish --tag beta
npm publish --tag next

Installing Packages

Install from Registry

npm install my-package

Install Scoped Package

npm install @mycompany/my-package

Install Specific Version

npm install my-package@1.0.0
npm install my-package@^1.0.0
npm install my-package@~1.2.3

Install from Specific Tag

npm install my-package@beta
npm install my-package@next

Scoped Packages

Scoped packages allow you to group related packages under a namespace.

Configure Scope

For organization scope @mycompany:

@mycompany:registry=http://localhost:8080/npm/
//localhost:8080/npm/:_authToken=your-auth-token

Create Scoped Package

{
  "name": "@mycompany/utils",
  "version": "1.0.0"
}

Publish Scoped Package

npm publish --access public

Install Scoped Package

npm install @mycompany/utils

Use Scoped Package

import { helper } from '@mycompany/utils';

Version Management

Semantic Versioning

Follow semantic versioning for your packages:

# Increment patch version (1.0.0 -> 1.0.1)
npm version patch

# Increment minor version (1.0.0 -> 1.1.0)
npm version minor

# Increment major version (1.0.0 -> 2.0.0)
npm version major

Then publish:

npm publish

Pre-release Versions

npm version prerelease --preid=beta
# 1.0.0 -> 1.0.1-beta.0

npm publish --tag beta

List Versions

View all published versions:

npm view my-package versions

Deprecate Version

Mark a version as deprecated:

npm deprecate my-package@1.0.0 "Use version 2.0.0 instead"

Tag Management

Add Tag

npm dist-tag add my-package@1.0.0 stable

Remove Tag

npm dist-tag rm my-package stable

List Tags

npm dist-tag ls my-package

Yarn Support

Artifact Keeper’s npm registry is fully compatible with Yarn.

Configure Yarn v1

yarn config set registry http://localhost:8080/npm/

Configure Yarn v2+

Edit .yarnrc.yml:

npmRegistryServer: "http://localhost:8080/npm/"

npmAuthToken: your-auth-token

Install with Yarn

yarn add my-package

Publish with Yarn

yarn publish

pnpm Support

Artifact Keeper’s npm registry is fully compatible with pnpm.

Configure pnpm

pnpm config set registry http://localhost:8080/npm/

Or in .npmrc:

registry=http://localhost:8080/npm/

Install with pnpm

pnpm add my-package

Publish with pnpm

pnpm publish

Integration with CI/CD

GitHub Actions

name: Publish Package
on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'http://localhost:8080/npm/'

      - run: npm ci

      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

GitLab CI

publish:
  image: node:20
  script:
    - echo "//localhost:8080/npm/:_authToken=${NPM_TOKEN}" > .npmrc
    - npm publish
  only:
    - tags

Jenkins Pipeline

pipeline {
    agent any

    tools {
        nodejs 'NodeJS 20'
    }

    stages {
        stage('Publish') {
            steps {
                withCredentials([
                    string(credentialsId: 'npm-token', variable: 'NPM_TOKEN')
                ]) {
                    sh '''
                        echo "//localhost:8080/npm/:_authToken=${NPM_TOKEN}" > .npmrc
                        npm publish
                    '''
                }
            }
        }
    }
}

Advanced Configuration

Multiple Registries

Use different registries for different scopes:

# Default registry
registry=https://registry.npmjs.org/

# Company packages
@mycompany:registry=http://localhost:8080/npm/
//localhost:8080/npm/:_authToken=token1

# Team packages
@myteam:registry=http://team-registry:8080/npm/
//team-registry:8080/npm/:_authToken=token2

Proxy Configuration

proxy=http://proxy.example.com:8080
https-proxy=http://proxy.example.com:8080

SSL/TLS Configuration

For self-signed certificates:

strict-ssl=false

Or add CA certificate:

cafile=/path/to/ca-certificate.crt

Package Scripts

Automate publishing with package scripts:

{
  "scripts": {
    "prepublishOnly": "npm test && npm run build",
    "preversion": "npm test",
    "version": "npm run build && git add -A",
    "postversion": "git push && git push --tags && npm publish"
  }
}

Troubleshooting

Authentication Errors

Verify your token is valid:

npm whoami --registry=http://localhost:8080/npm/

Publishing Failures

Check package name availability:

npm view my-package

Enable verbose logging:

npm publish --loglevel verbose

Installation Issues

Clear npm cache:

npm cache clean --force

Verify registry configuration:

npm config get registry
npm config list

Version Conflicts

Ensure version in package.json is incremented:

npm version patch  # Auto-increment
npm publish

Best Practices

Semantic Versioning

• Major (1.0.0 -> 2.0.0): Breaking changes
• Minor (1.0.0 -> 1.1.0): New features, backward compatible
• Patch (1.0.0 -> 1.0.1): Bug fixes

Package.json Fields

Include essential metadata:

{
  "name": "@mycompany/my-package",
  "version": "1.0.0",
  "description": "Clear, concise description",
  "keywords": ["keyword1", "keyword2"],
  "author": "Your Name <you@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/mycompany/my-package"
  },
  "bugs": {
    "url": "https://github.com/mycompany/my-package/issues"
  },
  "homepage": "https://github.com/mycompany/my-package#readme"
}

.npmignore

Exclude unnecessary files from published package:

.git
.github
tests
coverage
*.test.js
.env
.DS_Store
node_modules

See Also

• Security Scanning - Automatic vulnerability scanning for npm packages
• Security Policies - Configure policies to block vulnerable packages