warehouse13/frontend/REGISTRY-EXAMPLES.md

NPM Registry - Usage Examples

Quick Reference

Use Public NPM (Default)

# Linux/Mac
./quickstart.sh

# Windows
.\quickstart.ps1

Use Artifactory

# Linux/Mac
export ARTIFACTORY_AUTH_TOKEN="your_token_here"
./quickstart.sh -bsf

# Windows
$env:ARTIFACTORY_AUTH_TOKEN = "your_token_here"
.\quickstart.ps1 -Bsf

Rebuild with Artifactory

# Linux/Mac
export ARTIFACTORY_AUTH_TOKEN="your_token_here"
./quickstart.sh --rebuild -bsf

# Windows
$env:ARTIFACTORY_AUTH_TOKEN = "your_token_here"
.\quickstart.ps1 -Rebuild -Bsf

Local Development (Without Docker)

Switch Registry for Local Development

Linux/Mac:

cd frontend

# Switch to public npm
./switch-registry.sh public
npm ci --force
npm start

# Switch to Artifactory
./switch-registry.sh artifactory
export ARTIFACTORY_AUTH_TOKEN="your_token"
npm ci --force
npm start

Windows:

cd frontend

# Switch to public npm
.\switch-registry.ps1 public
npm ci --force
npm start

# Switch to Artifactory
.\switch-registry.ps1 artifactory
$env:ARTIFACTORY_AUTH_TOKEN = "your_token"
npm ci --force
npm start

Using NPM Scripts (Cross-platform):

cd frontend

# Switch to public npm
npm run registry:public
npm ci --force
npm start

# Switch to Artifactory
npm run registry:artifactory
npm ci --force
npm start

Docker Build Examples

Build Specific Service with Registry

Public NPM:

docker compose build app

Artifactory:

# Without auth
docker compose build app --build-arg NPM_REGISTRY=artifactory

# With auth
docker compose build app \
  --build-arg NPM_REGISTRY=artifactory \
  --build-arg ARTIFACTORY_AUTH_TOKEN="your_token"

Windows PowerShell:

docker compose build app `
  --build-arg NPM_REGISTRY=artifactory `
  --build-arg ARTIFACTORY_AUTH_TOKEN="your_token"

Common Workflows

Corporate Network Development

When working from a corporate network that requires Artifactory:

1. First time setup:

   # Edit .npmrc.artifactory with your Artifactory URL
   nano frontend/.npmrc.artifactory
   
   # Set auth token (get from your Artifactory admin)
   export ARTIFACTORY_AUTH_TOKEN="your_base64_token"
   
   # Start with Artifactory
   ./quickstart.sh -bsf
   

2. Daily development:

   export ARTIFACTORY_AUTH_TOKEN="your_token"
   ./quickstart.sh -bsf
   

Home/Public Network Development

When working from home or a network with npm access:

# Just run without -bsf flag
./quickstart.sh

Switching Between Environments

Moving from Corporate to Home:

# Stop existing containers
docker compose down

# Rebuild with public npm
./quickstart.sh --rebuild

Moving from Home to Corporate:

# Stop existing containers
docker compose down

# Rebuild with Artifactory
export ARTIFACTORY_AUTH_TOKEN="your_token"
./quickstart.sh --rebuild -bsf

Handling Multiple package-lock.json Files

Save lockfiles for both registries:

cd frontend

# Generate public lockfile
./switch-registry.sh public
rm package-lock.json
npm install
cp package-lock.json package-lock.public.json

# Generate artifactory lockfile
./switch-registry.sh artifactory
rm package-lock.json
npm install
cp package-lock.json package-lock.artifactory.json

# Add to git
git add package-lock.public.json package-lock.artifactory.json

Use the appropriate lockfile:

# When using public npm
cp package-lock.public.json package-lock.json
npm ci

# When using Artifactory
cp package-lock.artifactory.json package-lock.json
npm ci

CI/CD Examples

GitHub Actions

.github/workflows/build.yml

name: Build

on: [push, pull_request]

jobs:
  build-public:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build with public npm
        run: |
          docker compose build app
          docker compose up -d

  build-artifactory:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build with Artifactory
        env:
          ARTIFACTORY_AUTH_TOKEN: ${{ secrets.ARTIFACTORY_TOKEN }}
        run: |
          ./quickstart.sh -bsf

GitLab CI

.gitlab-ci.yml

variables:
  NPM_REGISTRY: "public"

build:public:
  stage: build
  script:
    - docker compose build app
    - docker compose up -d
  only:
    - main

build:artifactory:
  stage: build
  variables:
    NPM_REGISTRY: "artifactory"
  script:
    - export ARTIFACTORY_AUTH_TOKEN="${CI_ARTIFACTORY_TOKEN}"
    - ./quickstart.sh -bsf
  only:
    - develop

Jenkins Pipeline

Jenkinsfile

pipeline {
    agent any

    environment {
        ARTIFACTORY_AUTH_TOKEN = credentials('artifactory-npm-token')
    }

    stages {
        stage('Build with Artifactory') {
            steps {
                sh './quickstart.sh -bsf'
            }
        }
    }
}

Troubleshooting

Build fails with "Cannot find .npmrc.public"

Problem: Registry config files are missing.

Solution:

cd frontend
# Verify files exist
ls -la .npmrc.*

# If missing, they should be committed to git
git status

"ENOENT: no such file or directory, open '/frontend/dist/frontend/browser'"

Problem: Frontend build failed due to registry issues.

Solution:

# Check build logs
docker compose logs app | grep npm

# Try rebuilding with verbose logging
docker compose build app --no-cache --progress=plain

npm ci fails with 404 errors

Problem: Wrong registry is configured.

Solution:

cd frontend
cat .npmrc  # Check which registry is active

# If using wrong one, switch:
npm run registry:public   # or registry:artifactory
npm ci --force

Authentication fails with Artifactory

Problem: Token is invalid or not set.

Solution:

# Check token is set
echo $ARTIFACTORY_AUTH_TOKEN  # Linux/Mac
echo $env:ARTIFACTORY_AUTH_TOKEN  # Windows

# Get new token from Artifactory UI:
# Artifactory -> User Profile -> Generate Token

# Set the token
export ARTIFACTORY_AUTH_TOKEN="your_new_token"