npm ci requires package-lock.json: Solutions and Best Practices

Problem Overview

The error npm ci can only install packages with an existing package-lock.json or npm-shrinkwrap.json with lockfileVersion >= 1 occurs when npm's clean install command cannot find a valid lockfile or encounters issues with the existing lockfile.

This commonly happens in CI/CD environments when there's a mismatch between development and CI environments, or when using multiple package managers in the same project.

Root Causes

Missing or Invalid Lockfile

• No package-lock.json file exists (common when using Yarn or pnpm)
• Corrupted or malformed package-lock.json (syntax errors, merge conflicts)

Environment Version Mismatches

• Different Node.js versions between local and CI environments
• Different npm versions across environments
• Package-lock generated with different npm configurations

Package Manager Conflicts

• Mixed usage of npm, Yarn, and pnpm in the same project
• Inconsistent lockfile generation methods

Solutions

1. Generate Missing Lockfile

If you're missing package-lock.json entirely:

npm install --package-lock-only

This generates a lockfile without installing node_modules, which is ideal for CI environments.

2. Resync Package and Lockfile

When package.json and package-lock.json are out of sync:

# Delete existing lockfile and node_modules
rm package-lock.json
rm -rf node_modules

# Regenerate lockfile
npm install

WARNING

Always commit the updated package-lock.json to version control after regeneration.

3. Handle Multiple Package Managers

For projects using both npm and Yarn:

# GitHub Actions example
- name: Install dependencies
  run: |
    if [ -e yarn.lock ]; then
      yarn install --frozen-lockfile
    elif [ -e package-lock.json ]; then
      npm ci
    else
      npm i
    fi

4. Ensure Environment Consistency

Specify Node.js and npm versions in your project:

// package.json
"engines": {
  "node": "18.20.2",
  "npm": "10.5.0"
}

Use version managers in CI:

# GitHub Actions example
- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18.x'
    cache: 'npm'

5. Check npm Configuration

Verify you don't have conflicting global npm settings:

# Check current config
npm config list

# Remove problematic settings if needed
npm config delete legacy-peer-deps

6. AWS Amplify Specific Solution

For AWS Amplify builds, update your build specification:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm install --package-lock-only
        - npm ci
    build:
      commands:
        - npm run build

Best Practices

Version Control

• Always commit package-lock.json to version control
• Ensure consistent Node.js versions across environments
• Use .nvmrc or engines field to specify Node version

CI/CD Optimization

• Cache node_modules between builds when possible
• Use platform-specific caching solutions:

# GitHub Actions cache example
- name: Cache node modules
  uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

Choosing Between npm ci and npm install

Scenario	Recommended Command
CI/CD environments	npm ci
Local development	npm install
Adding new dependencies	npm install <package>
Reproducible builds	npm ci

Troubleshooting Checklist

1. ✅ Verify package-lock.json exists and is valid JSON
2. ✅ Check Node.js and npm version consistency
3. ✅ Ensure no global npm config conflicts
4. ✅ Confirm package.json and lockfile are synced
5. ✅ Use appropriate package manager for existing lockfiles

When to Use Alternative Package Managers

If you're using Yarn or pnpm, update your CI configuration accordingly:

# For Yarn
- name: Install dependencies
  run: yarn install --frozen-lockfile

# For pnpm
- name: Install dependencies
  run: |
    npm i -g pnpm
    pnpm i

DANGER

Avoid mixing package managers in the same project. Choose one and ensure all team members use it consistently.

By following these solutions and best practices, you can resolve the npm ci error and ensure reliable, reproducible dependency installation across all environments.