Package.json Linter: Como Validar com ESLint Plugin

Aprenda a usar o eslint-plugin-package-json para validar e padronizar seu package.json automaticamente. Evite erros de publicação NPM, inconsistências em monorepos e problemas gerados por IA no seu projeto JavaScript: Como Validar com ESLint Plugin.

Por que seu package.json merece um linter dedicado

O package.json é o documento de identidade do seu projeto JavaScript. Ele carrega metadados, scripts, dependências e configurações que afetam diretamente a publicação no NPM, a instalação de pacotes e a integração com ferramentas de CI/CD. Um arquivo mal formatado pode quebrar deploys, impedir publicações e gerar bugs difíceis de rastrear. É aí que entra o eslint-plugin-package-json: um plugin ESLint que traz validação automática, padronização e boas práticas diretamente para o coração do seu projeto.

Cenários onde este plugin resolve problemas reais

• Monorepos com múltiplos pacotes: manter dezenas de package.json consistentes manualmente é impossível.
• Projetos open source: campos como license, repository e author precisam estar sempre corretos.
• Times com diferentes níveis de experiência: o plugin ensina boas práticas automaticamente, reduzindo erros.
• Prevenção de falhas de publicação: detecta problemas antes que cheguem ao registro NPM.

IA e tokens de codificação: o problema silencioso

Ferramentas como GitHub Copilot, ChatGPT e Cursor estão cada vez mais presentes no fluxo de desenvolvimento. Elas geram código rapidamente, mas quando o assunto é package.json, costumam produzir inconsistências perigosas:

Problema gerado por IA	Exemplo
Versões inválidas	"react": "latest" ou "^18" (incompleto)
Campos duplicados	Mesclar código gerado cria dependências repetidas
Licenças incorretas	"license": "MIT License" em vez de "MIT"
Tipos errados	"name": 123 (deveria ser string)
Ordenação aleatória	Mistura de tabs, espaços e campos fora de ordem

O eslint-plugin-package-json funciona como uma camada de validação pós-IA, capturando esses erros automaticamente antes que causem problemas.

Instalação e configuração passo a passo

Pré-requisitos

• Node.js 14 ou superior
• ESLint 8+ instalado no projeto

Passo 1: Instalar dependências

npm install --save-dev eslint eslint-plugin-package-json

Passo 2: Configurar o ESLint

Crie ou atualize seu arquivo .eslintrc.json:

{
  "root": true,
  "plugins": ["package-json"],
  "overrides": [
    {
      "files": ["package.json"],
      "parser": "eslint-plugin-package-json/parser",
      "rules": {
        "package-json/valid-package-def": "error",
        "package-json/require-author": "error",
        "package-json/require-license": "error",
        "package-json/require-repository": "error",
        "package-json/sort-collections": "error",
        "package-json/valid-name": "error",
        "package-json/valid-version": "error"
      }
    }
  ]
}

Passo 3: Adicionar scripts

{
  "scripts": {
    "lint": "eslint .",
    "lint:package-json": "eslint package.json"
  }
}

Passo 4: Executar a validação

npm run lint:package-json

Regras que fazem a diferença

valid-package-def

Detecta JSON malformado e campos com tipos incorretos.

// ❌ Errado
{
  "name": 123,        // Deveria ser string
  "version": null,    // Deveria ser string
  "scripts": "build"  // Deveria ser objeto
}

sort-collections

Mantém dependências em ordem alfabética, facilitando a leitura.

// ❌ Desordenado
{
  "devDependencies": {
    "eslint": "^8.0.0",
    "vitest": "^1.0.0",
    "prettier": "^3.0.0"  // Fora de ordem
  }
}

valid-version

Rejeita versões inválidas frequentemente geradas por IA.

// ❌ Formatos problemáticos
{
  "dependencies": {
    "lodash": "latest",    // Não é versão válida
    "react": "^18",        // Semver incompleto
    "axios": "*"           // Permissivo demais
  }
}

Configuração recomendada para projetos open source

{
  "overrides": [
    {
      "files": ["package.json"],
      "parser": "eslint-plugin-package-json/parser",
      "rules": {
        "package-json/valid-package-def": "error",
        "package-json/require-author": "error",
        "package-json/require-license": "error",
        "package-json/require-repository": "error",
        "package-json/require-version": "error",
        "package-json/require-keywords": "error",
        "package-json/require-bugs": "warn",
        "package-json/require-homepage": "warn",
        "package-json/sort-collections": "error",
        "package-json/valid-name": "error",
        "package-json/no-redundant-files": "error",
        "package-json/prefer-repository-shorthand": "warn"
      }
    }
  ]
}

Integração com Git Hooks

Automatize a validação antes de cada commit com husky e lint-staged:

npm install --save-dev husky lint-staged

// No package.json
{
  "lint-staged": {
    "package.json": "eslint --fix"
  }
}

Antes e depois

Antes do plugin	Depois do plugin
❌ 3h debugando erro de publicação	✅ Zero erros em produção
❌ PRs rejeitados por problemas simples	✅ PRs aprovados na primeira tentativa
❌ Pacotes publicados sem campos obrigatórios	✅ Consistência total no monorepo
❌ Code review desperdiçando tempo	✅ Tempo de review reduzido em 40%

Dica extra

Combine este plugin com o eslint-plugin-jsonc para validar outros arquivos JSON do projeto, como configurações de TypeScript e Prettier. Assim, toda a base de configuração do seu projeto fica protegida.

---

O eslint-plugin-package-json resolve em minutos uma categoria inteira de problemas que assombram times de desenvolvimento. Em uma era onde código gerado por IA é cada vez mais comum, ter validações automatizadas para arquivos críticos como o package.json não é luxo — é necessidade.