warehouse13/frontend/README-REGISTRY.md

NPM Registry Configuration

This project supports working with two different npm registries:

1. Public registry - registry.npmjs.org (default)
2. Artifactory - Your corporate Artifactory npm registry

Quick Start

Switching Registries Locally

On Linux/Mac:

cd frontend

# Use public npm registry (default)
./switch-registry.sh public
npm ci --force

# Use Artifactory registry
./switch-registry.sh artifactory
# Set auth token if required
export ARTIFACTORY_AUTH_TOKEN="your_token_here"
npm ci --force

On Windows:

cd frontend

# Use public npm registry (default)
.\switch-registry.ps1 public
npm ci --force

# Use Artifactory registry
.\switch-registry.ps1 artifactory
# Set auth token if required
$env:ARTIFACTORY_AUTH_TOKEN = "your_token_here"
npm ci --force

Building with Docker

Using public npm registry (default):

docker compose build app

Using Artifactory registry:

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

# With authentication
docker compose build app \
  --build-arg NPM_REGISTRY=artifactory \
  --build-arg ARTIFACTORY_AUTH_TOKEN="your_token_here"

On Windows PowerShell:

# With authentication
docker compose build app `
  --build-arg NPM_REGISTRY=artifactory `
  --build-arg ARTIFACTORY_AUTH_TOKEN="your_token_here"

Configuration Files

• .npmrc.public - Configuration for public npm registry
• .npmrc.artifactory - Configuration for Artifactory registry (edit this with your Artifactory URL)
• .npmrc - Active configuration (generated by switch-registry scripts)

Setup Artifactory Configuration

1. Edit frontend/.npmrc.artifactory and replace YOUR_ARTIFACTORY_URL with your actual Artifactory URL:

   registry=https://artifactory.yourcompany.com/artifactory/api/npm/npm-virtual/
   

2. If authentication is required, uncomment the auth lines and use one of these methods:

   Method 1: Auth Token (Recommended)

   //artifactory.yourcompany.com/artifactory/api/npm/npm-virtual/:_auth=${ARTIFACTORY_AUTH_TOKEN}
   //artifactory.yourcompany.com/artifactory/api/npm/npm-virtual/:always-auth=true
   

   Then set the environment variable:

   export ARTIFACTORY_AUTH_TOKEN="your_base64_encoded_token"
   

   Method 2: Username/Password

   //artifactory.yourcompany.com/artifactory/api/npm/npm-virtual/:username=${ARTIFACTORY_USERNAME}
   //artifactory.yourcompany.com/artifactory/api/npm/npm-virtual/:_password=${ARTIFACTORY_PASSWORD}
   //artifactory.yourcompany.com/artifactory/api/npm/npm-virtual/:email=your-email@company.com
   

Handling package-lock.json

The package-lock.json file will be different depending on which registry you use. Here are strategies to manage this:

Strategy 1: Separate Lockfiles (Recommended)

Keep two lockfiles and switch between them:

# After switching to public and installing
npm ci --force
cp package-lock.json package-lock.public.json

# After switching to artifactory and installing
npm ci --force
cp package-lock.json package-lock.artifactory.json

# When switching registries in the future
cp package-lock.public.json package-lock.json     # or
cp package-lock.artifactory.json package-lock.json

Strategy 2: Regenerate Lockfile

Always regenerate the lockfile after switching:

./switch-registry.sh artifactory
rm package-lock.json
npm install

Strategy 3: Git Ignore Lockfile (Not Recommended for Production)

If you're frequently switching and don't need deterministic builds:

Add to .gitignore:

frontend/package-lock.json

Warning: This reduces build reproducibility.

Troubleshooting

Issue: "npm ci requires package-lock.json"

Solution: Delete package-lock.json and run npm install to generate a new one for your current registry.

Issue: "404 Not Found - GET https://registry.npmjs.org/..."

Solution: Your .npmrc is pointing to Artifactory but packages don't exist there.

./switch-registry.sh public
npm ci --force

Issue: "401 Unauthorized"

Solution: Check your authentication configuration in .npmrc.artifactory and ensure environment variables are set correctly.

Issue: "ENOENT: no such file or directory, open '.npmrc.public'"

Solution: You're missing the registry config files. Make sure both .npmrc.public and .npmrc.artifactory exist in the frontend directory.

CI/CD Integration

For CI/CD pipelines, use environment variables to select the registry:

GitHub Actions Example:

- name: Build with Artifactory
  env:
    NPM_REGISTRY: artifactory
    ARTIFACTORY_AUTH_TOKEN: ${{ secrets.ARTIFACTORY_TOKEN }}
  run: |
    docker compose build app \
      --build-arg NPM_REGISTRY=artifactory \
      --build-arg ARTIFACTORY_AUTH_TOKEN="${ARTIFACTORY_AUTH_TOKEN}"

GitLab CI Example:

build:
  script:
    - docker compose build app
        --build-arg NPM_REGISTRY=artifactory
        --build-arg ARTIFACTORY_AUTH_TOKEN="${ARTIFACTORY_AUTH_TOKEN}"
  variables:
    NPM_REGISTRY: artifactory
    ARTIFACTORY_AUTH_TOKEN: ${CI_ARTIFACTORY_TOKEN}

Best Practices

1. Never commit credentials - Use environment variables for tokens/passwords
2. Document your Artifactory URL - Update .npmrc.artifactory with your team's URL
3. Keep both config files - Commit .npmrc.public and .npmrc.artifactory to git
4. Use the scripts - Always use switch-registry.sh/ps1 instead of manually editing .npmrc
5. Clean installs - Use npm ci --force after switching to ensure a clean dependency tree