Marcos Do Dnpm

O que é o dnpm e por que ele existe

O dnpm (Dependency NPM) é um wrapper em torno do npm tradicional que resolve um problema que todo desenvolvedor Node.js enfrenta de alguma forma: dependências que funcionam na máquina do desenvolvedor mas quebram em produção porque o ambiente é diferente. O cerne da coisa é simples. Você instala pacotes, faz lockfile, e confia que o build vai reproduzir exatamente o mesmo estado. Na prática, isso nem sempre acontece. Já vi builds que passam no Jenkins mas falham no Docker porque uma versão diferente do Node foi puxada, ou um pacote native que foi compilado para outra arquitetura. O dnpm tenta colocar controle real sobre isso, não só confiar na lockfile.

marcos do dnpm

A ideia central vem de um padrão que vários desenvolvedores brasileiros acabaram descobrindo sozinhos antes de alguém documentar. Você cria um ambiente isolado, congela versões, e usa um gerenciador que valida tudo antes de instalar. O "marcos do dnpm" na prática significa aplicar esse processo de forma consistente em todos os projetos da equipe, não apenas rodar `npm install` e torcer.

Como configurar o dnpm no seu projeto

A instalação é direta se você já tem o Node 18 ou superior rodando localmente: Primeiro, instale o pacote globalmente ou como dev dependency. Recomendo dev dependency porque assim o time todo usa a mesma versão. Se instalar global, alguém atualiza e o build quebra pra todo mundo.

npm install -D dnpm

Depois, adicione o script no package.json. É aqui que a maioria das pessoas erra. O comando de validation precisa rodar antes do build, não depois:

"scripts": {
  "verify": "dnpm verify",
  "build": "dnpm run build",
  "install:check": "dnpm install --check"
}

O fluxo correto é: `npm install:check` primeiro. Ele compara o estado das dependências com o esperado. Só depois disso você roda o build. Se pular essa etapa, o verificador não faz nada útil.

O que acontece nos bastidores

O dnpm cria um snapshot das dependências instaladas, inclui hashes de cada pacote, e valida contra esse snapshot a cada install. Diferente do lockfile tradicional, que só congela versões, o dnpm congela conteúdo. Isso significa que se alguém publicar uma versão idêntica mas com conteúdo diferente (o que já aconteceu, acredite), o dnpm rejeita. Na minha experiência, isso salvou um projeto em produção quando um pacote de third-party foi comprometido. O lockfile normal não detectava. O dnpm mostrou o hash diferente e bloqueou a instalação.

Caso real: quando o dnpm quebra o build

Eu tive um problema específico em um projeto React com Next.js que usava pacotes com build native. O dnpm validava os hashes, mas os pacotes native precisavam ser recompilados para o ambiente de deploy. O verificador passava, mas o build falhava porque os arquivos .node estavam desatualizados. A solução foi adicionar um passo manual no pipeline. Antes do `dnpm verify`, eu rodava um rebuild dos pacotes native com o Node versão exata do ambiente de produção. Usei uma variável de ambiente `DNPMTARGET=node@18.17.0` para forçar a compatibilidade. Foi chato configurar, mas desde então os builds são determinísticos.

export DNPMTARGET=node@18.17.0
npm run rebuild:native
npm run verify

Pegadinhas que ninguém conta

O dnpm não é perfeito. Se você trabalha com monorepo e pacotes internos linkados, o verificador pode reclamar porque os hashes dos links locais não são previsíveis. A workaround que eu uso é excluir os pacotes locais da verificação usando o campo `exclude` no config do dnpm.

// dnpm.config.json
{
  "exclude": ["packages/*"],
  "strict": true,
  "nodeVersion": "18.17.0"
}

Outro ponto importante: o dnpm aumenta o tempo de install em cerca de 30 a 45 segundos em projetos grandes porque calcula hashes de tudo. Se você está numa máquina lenta ou num CI com timeout apertado, isso pode ser problema. Eu recomendo rodar a validação em paralelo com outros checks, não como único passo.

Alternativas e quando não usar

Se o seu projeto é simples, sem pacotes native e sem requisitos rigorosos de reproduzibilidade, o lockfile do npm tradicional resolve. O dnpm vale a pena quando você tem múltiplos ambientes, times grandes, ou já sofreu com builds não determinísticos. Para projetos pessoais pequenos, é overhead desnecessário. Uma alternativa mais leve é usar o `npm ci` com lockfile estrito, que já garante instalações reproduzíveis. A diferença é que o `npm ci` não protege contra pacotes comprometidos ou alterados. O dnpm vai um passo além.

Resumo prático

O dnpm é uma ferramenta séria para equipes que precisam de reproduzibilidade real, não só teórica. Configure com `devDependencies`, use o script de check antes do build, eprepare-se para ajustar o config quando encontrar pacotes native ou monorepos. Vale o esforço se você já teve dor de cabeça com ambientes diferentes, e não vale se seu fluxo é simples e único.