npm install vs npm ci: O Guia DEFINITIVO!

💡 TL;DR (Resumo)

Desenvolvimento: Use npm install (ou npm i) para adicionar, remover ou atualizar pacotes. Ele pode modificar seu package-lock.json.

Produção/CI/CD: Use npm ci para instalar dependências. Ele é mais rápido, mais seguro e garante builds 100% reprodutíveis usando exatamente as versões do package-lock.json. Ele nunca modifica seus arquivos package.json ou package-lock.json.

📊 Tabela Comparativa Completa

Aspecto	`npm install`	`npm ci`
Velocidade	Média (10-30s)	Rápida (5-15s)
Determinístico	❌ Não garantido	✅ 100% reproduzível
Modifica `package.json`	❌ Não	❌ Não
Modifica `package-lock.json`	✅ Sim	❌ Nunca
Requer `package-lock.json`	❌ Opcional	✅ Obrigatório
Remove `node_modules` antes	❌ Não	✅ Sim (automático)
Instala `devDependencies`	✅ Sim	✅ Sim (pode desativar)
Aceita ranges (^, ~)	✅ Sim	❌ Não (só exato)
Adiciona novas deps	✅ Sim	❌ Não
Cache	Usa	Otimizado
Uso ideal	Desenvolvimento Local	CI/CD & Produção

🔍 Explicação Detalhada

`npm install` (ou `npm i`)

Como funciona:

bash

npm install

# Passos internos:
# 1. Lê package.json
# 2. Lê package-lock.json (se existir)
# 3. Resolve árvore de dependências
# 4. Compara com node_modules existente
# 5. Atualiza apenas o necessário
# 6. PODE modificar package-lock.json
# 7. Instala em node_modules

Quando usar:

✅ Primeira vez no projeto:

bash

git clone https://github.com/seu-projeto.git
cd seu-projeto
npm install  # Cria package-lock.json

✅ Adicionar nova dependência:

bash

npm install lodash
npm install --save-dev typescript

✅ Atualizar dependências:

bash

npm install lodash@latest
npm update

✅ Desenvolvimento ativo:

bash

# Trabalhando localmente
npm install

Comportamento com versões:

json

{
  "dependencies": {
    "next": "^15.0.3"
  }
}

bash

# Se 15.0.5 foi lançado:
npm install  
# Pode instalar 15.0.5 (dentro do range ^)
# Atualiza package-lock.json com 15.0.5

`npm ci` (Clean Install)

Como funciona:

bash

npm ci

# Passos internos:
# 1. Verifica se package-lock.json existe (OBRIGATÓRIO)
# 2. Remove node_modules COMPLETAMENTE
# 3. Instala EXATAMENTE as versões do lock
# 4. NUNCA modifica package-lock.json
# 5. Falha se package.json e lock não batem
# 6. Mais rápido (otimizado)

Quando usar:

✅ CI/CD Pipelines (SEMPRE!):

yaml

# .github/workflows/ci.yml
- name: Install dependencies
  run: npm ci  # Garante reprodutibilidade

✅ Builds de produção (SEMPRE!):

bash

# No servidor
git pull
npm ci
npm run build

✅ Ambientes de teste:

bash

# Docker
RUN npm ci --only=production

✅ Após git pull (RECOMENDADO):

bash

git pull origin main
npm ci  # Garante mesmas versões do time

✅ Limpar problemas:

bash

# Algo quebrou? Limpar tudo
npm ci  # Remove node_modules e reinstala

Comportamento com versões:

json

// package.json
{
  "dependencies": {
    "next": "^15.0.3"
  }
}

// package-lock.json
{
  "next": {
    "version": "15.0.3"
  }
}

bash

# Mesmo que 15.0.5 exista:
npm ci
# Instala EXATAMENTE 15.0.3 (do lock)

🎮 Exemplos de Uso no Mundo Real

Cenário 1: Novo desenvolvedor no time

bash

# Dia 1 - Clonar projeto
git clone https://github.com/empresa/projeto.git
cd projeto

# Opção A: npm install (funciona)
npm install

# Opção B: npm ci (MELHOR - mais rápido e exato)
npm ci

# Por quê npm ci?
# - Mais rápido
# - Garante mesmas versões do time
# - Evita "funciona na minha máquina"

Cenário 2: Adicionar biblioteca

bash

# Precisa adicionar Express
npm install express

# npm ci NÃO funciona aqui!
# npm ci não adiciona pacotes

# Depois de adicionar:
git add package.json package-lock.json
git commit -m "Add express"
git push

Cenário 3: Pull Request Review

bash

# Baixar PR para testar
git fetch origin pull/123/head:pr-123
git checkout pr-123

# Use npm ci (garante deps exatas do PR)
npm ci
npm run build
npm run test

Cenário 4: Deploy automatizado

bash

# Script de deploy
#!/bin/bash
set -e

echo "Deploying to production..."

# 1. Pull latest
git pull origin main

# 2. Install dependencies (USE npm ci!)
npm ci --only=production  # Só produção, mais rápido

# 3. Build
npm run build

# 4. Restart
pm2 restart app

Cenário 5: Dockerfile otimizado

dockerfile

FROM node:20-alpine

WORKDIR /app

# Copiar package files
COPY package*.json ./

# USE npm ci no Docker!
RUN npm ci --only=production

# Copiar código
COPY . .

# Build
RUN npm run build

CMD ["npm", "start"]

Cenário 6: GitHub Actions

yaml

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'npm'  # Cache do npm ci
      
      - name: Install dependencies
        run: npm ci  # SEMPRE use npm ci aqui!
      
      - name: Type check
        run: npm run type-check
      
      - name: Lint
        run: npm run lint
      
      - name: Build
        run: npm run build
      
      - name: Test
        run: npm run test

⚠️ Problemas Comuns e Soluções

Problema 1: npm ci falha com "no such file package-lock.json"

bash

# Erro:
npm ci
# Error: The package-lock.json file is missing

# Causa: package-lock.json não está commitado

# Solução:
npm install  # Cria o lock
git add package-lock.json
git commit -m "Add package-lock.json"

Prevenção:

gitignore

# NÃO adicione isto no .gitignore!
# package-lock.json  ❌ NUNCA!

# Sempre commite o package-lock.json

Problema 2: "Funciona na minha máquina, mas não no CI"

bash

# Dev:
npm install  # Instala versão 15.0.5

# CI:
npm ci      # Instala versão 15.0.3 (do lock antigo)

# Problema: Versões diferentes!

# Solução: Sempre commit o lock atualizado
npm install  # Atualiza lock
git add package-lock.json
git commit -m "Update dependencies"
git push

Problema 3: npm ci está lento

bash

# npm ci deveria ser mais rápido, mas está lento?

# Causa 1: Cache desativado
npm config get cache
# Se vazio, configurar:
npm config set cache ~/.npm --global

# Causa 2: node_modules muito grande
# npm ci remove antes de instalar, pode demorar

# Solução: Limpar antes
rm -rf node_modules
npm ci

Problema 4: Conflito entre package.json e lock

bash

npm ci
# Error: The package-lock.json was created for a different version

# Causa: package.json mudou mas lock não foi atualizado

# Solução:
npm install  # Atualiza o lock
npm ci      # Agora funciona

🎯 Regras de Decisão

Use `npm install` quando:

bash

# ✅ Adicionar/remover pacotes
npm install express
npm uninstall lodash

# ✅ Atualizar dependências
npm update
npm install react@latest

# ✅ Primeiro setup (criar lock)
npm install

# ✅ Desenvolvimento local ativo
npm install

Use `npm ci` quando:

bash

# ✅ CI/CD (SEMPRE!)
npm ci

# ✅ Produção (SEMPRE!)
npm ci --only=production

# ✅ Após clonar repositório
git clone ... && npm ci

# ✅ Após git pull
git pull && npm ci

# ✅ Testes automatizados
npm ci && npm test

# ✅ Docker builds
RUN npm ci

# ✅ Garantir reprodutibilidade
npm ci

📈 Performance Benchmark

Projeto médio (100 deps):

bash

# Primeira instalação
npm install    # ~25 segundos
npm ci         # ~15 segundos (40% mais rápido!)

# Instalação com cache
npm install    # ~10 segundos
npm ci         # ~5 segundos  (50% mais rápido!)

# Com node_modules existente
npm install    # ~8 segundos  (apenas updates)
npm ci         # ~15 segundos (remove tudo antes)

Conclusão:

npm ci é mais rápido quando não há node_modules
npm install pode ser mais rápido se node_modules já existe

🛠️ Comandos úteis relacionados

bash

# Ver o que seria instalado (sem instalar)
npm install --dry-run

# Instalar apenas produção
npm ci --only=production
npm install --production

# Forçar reinstalação completa
rm -rf node_modules package-lock.json
npm install

# Ver diferenças entre package.json e lock
npm ls --depth=0

# Verificar integridade do lock
npm audit

# Limpar cache antes de instalar
npm cache clean --force
npm ci

🎨 Scripts Recomendados

Adicione ao seu package.json:

json

{
  "scripts": {
    "install:ci": "npm ci",
    "install:fresh": "rm -rf node_modules package-lock.json && npm install",
    "install:prod": "npm ci --only=production",
    "postinstall": "echo 'Dependencies installed successfully!'",
    "preinstall": "node -v && npm -v"
  }
}

✅ Checklist Final

Para Desenvolvimento:

Use npm install para adicionar deps
Commite package-lock.json sempre
Use npm ci após git pull
Não ignore package-lock.json no git

Para CI/CD:

SEMPRE use npm ci
Ative cache do npm
Use --only=production se possível
Falhe o build se npm ci falhar

Para Produção:

SEMPRE use npm ci --only=production
Nunca use npm install em produção
Verifique package-lock.json antes do deploy
Mantenha Node.js atualizado

📚 Resumo Visual

npm install	npm ci
📝 Desenvolvimento	🚀 CI/CD
➕ Adicionar deps	✅ Produção
🔄 Atualizar deps	🔒 Reprodução
🎨 Criar lock	⚡ Performance

🎓 Resumo Executivo

Para 99% dos casos:

Desenvolvimento local: npm install
CI/CD e Produção: npm ci
Após git pull: npm ci
Adicionar deps: npm install <package>
Problemas: rm -rf node_modules && npm ci

Regra de ouro:

Se você vai modificar dependências → npm install
Se você vai instalar dependências → npm ci

npm install vs npm ci: O Guia DEFINITIVO!

✨TL;DR / Sumário Executivo

💡 TL;DR (Resumo)

📊 Tabela Comparativa Completa

🔍 Explicação Detalhada

`npm install` (ou `npm i`)

Como funciona:

Quando usar:

Comportamento com versões:

`npm ci` (Clean Install)

Como funciona:

Quando usar:

Comportamento com versões:

🎮 Exemplos de Uso no Mundo Real

Cenário 1: Novo desenvolvedor no time

Cenário 2: Adicionar biblioteca

Cenário 3: Pull Request Review

Cenário 4: Deploy automatizado

Cenário 5: Dockerfile otimizado

Cenário 6: GitHub Actions

⚠️ Problemas Comuns e Soluções

Problema 1: npm ci falha com "no such file package-lock.json"

Problema 2: "Funciona na minha máquina, mas não no CI"

Problema 3: npm ci está lento

Problema 4: Conflito entre package.json e lock

🎯 Regras de Decisão

Use `npm install` quando:

Use `npm ci` quando:

📈 Performance Benchmark

Projeto médio (100 deps):

🛠️ Comandos úteis relacionados

🎨 Scripts Recomendados

✅ Checklist Final

Para Desenvolvimento:

Para CI/CD:

Para Produção:

📚 Resumo Visual

🎓 Resumo Executivo

Receba novos artigos