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:**
```bash
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:**
```powershell
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):**
```bash
docker compose build app
```

**Using Artifactory registry:**
```bash
# 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:**
```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:
   ```bash
   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:

```bash
# 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:

```bash
./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.
```bash
./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:**
```yaml
- 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:**
```yaml
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