@digdigital/eslint-config-frontend

Configuração compartilhada de ESLint para aplicações frontend da Dig Digital.

Este pacote reúne regras para JavaScript, TypeScript, React, acessibilidade e testes. Ele também integra o Prettier ao ESLint para que problemas de qualidade e formatação sejam identificados no mesmo fluxo de lint.

O que está incluído

• ESLint 8 e TypeScript;
• regras baseadas em Airbnb;
• React e React Hooks;
• @typescript-eslint;
• acessibilidade com eslint-plugin-jsx-a11y;
• testes com Testing Library e Jest DOM;
• ordenação de imports;
• formatação com Prettier;
• regras específicas da Dig Digital, incluindo a proteção contra exposição de variáveis de ambiente no frontend.

As regras são aplicadas a arquivos .js, .jsx, .ts e .tsx. A configuração usa o formato tradicional do ESLint (.eslintrc) e, portanto, não deve ser combinada com uma configuração flat (eslint.config.js) sem uma adaptação específica.

Requisitos

O projeto consumidor precisa ter Node.js, um gerenciador de pacotes e ESLint instalado. As versões exatas das dependências necessárias são declaradas como peerDependencies deste pacote e devem ser instaladas no próprio projeto.

Instalação

Adicione o pacote como dependência de desenvolvimento:

yarn add --dev @digdigital/eslint-config-frontend

Com npm:

npm install --save-dev @digdigital/eslint-config-frontend

Em seguida, instale as dependências peer recomendadas pelo pacote. O script abaixo imprime os nomes e as versões compatíveis:

node node_modules/@digdigital/eslint-config-frontend/install-peer-dependencies.js | xargs yarn add --dev

Se o projeto usa npm, substitua o gerenciador no final do comando:

node node_modules/@digdigital/eslint-config-frontend/install-peer-dependencies.js | xargs npm install --save-dev

Caso alguma dessas dependências já exista no projeto, confira se a versão instalada atende à versão exigida. Depois da instalação, valide o resultado com yarn lint ou npm run lint.

Configuração

Adicione a configuração ao package.json do projeto:

{
  "eslintConfig": {
    "extends": [
      "@digdigital/eslint-config-frontend"
    ]
  }
}

Como alternativa, crie um arquivo .eslintrc.json na raiz do projeto:

{
  "extends": ["@digdigital/eslint-config-frontend"]
}

Mantenha apenas uma configuração principal para evitar comportamentos difíceis de diagnosticar. Se houver configurações locais, elas serão mescladas pelo ESLint e poderão substituir as regras deste pacote.

Scripts recomendados

Inclua um script de lint no package.json:

{
  "scripts": {
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx"
  }
}

Execute a verificação com:

yarn lint
# ou
npm run lint

Para verificar somente arquivos específicos:

yarn eslint src --ext .js,.jsx,.ts,.tsx

O arquivo .eslintignore publicado pelo pacote já exclui diretórios gerados, como dist, build, coverage e node_modules. Regras adicionais podem ser colocadas em um .eslintignore local.

Correção automática

O ESLint pode corrigir automaticamente parte dos problemas encontrados:

yarn lint --fix
# ou
npm run lint -- --fix

Revise as alterações antes de criar o commit. Nem todos os problemas podem ser corrigidos automaticamente, especialmente aqueles que exigem decisão sobre comportamento ou arquitetura.

Integração com o VS Code

1. Instale a extensão ESLint.
2. Adicione .vscode/settings.json ao projeto:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.format.enable": true,
  "editor.formatOnSave": true
}

Não é necessário instalar a extensão do Prettier para usar a configuração deste pacote. Se ela estiver instalada, evite habilitar dois formatadores para o mesmo tipo de arquivo.

Migração de um projeto existente

Ao migrar de outra configuração compartilhada, faça a transição de forma controlada:

1. Remova os pacotes antigos de configuração, ESLint, plugins e Prettier que serão substituídos. Prefira yarn remove ou npm uninstall para manter o lockfile consistente.
2. Remova configurações antigas que não serão mais usadas (.eslintrc.*, .eslintignore, .prettierrc e .prettierignore). Preserve somente regras locais que ainda sejam necessárias.
3. Instale @digdigital/eslint-config-frontend e suas peer dependencies.
4. Adicione o bloco eslintConfig ou o arquivo .eslintrc.json descrito acima.
5. Execute yarn lint (ou npm run lint) e corrija os problemas. Use --fix para as correções seguras e revise manualmente o restante.
6. Execute novamente o lint e os testes do projeto antes de enviar as alterações.

Contribuições e solicitações de mudança

Antes de propor uma alteração, verifique se a regra é aplicável a todos os projetos consumidores e se não existe uma configuração local adequada para o caso específico.

Ao alterar a configuração:

1. atualize a regra e sua justificativa;
2. valide o próprio pacote com yarn lint;
3. teste a mudança em um projeto consumidor representativo;
4. descreva impactos, falsos positivos e eventuais passos de migração.

Issues e merge requests devem ser abertas no repositório oficial do projeto: digdigital/eslint-config-frontend.

Publicação de uma nova versão no npm

As publicações são realizadas pelo workflow Create release tag do GitHub Actions. Antes de iniciar, confirme que as alterações já foram revisadas e estão na branch master, que o secret NPM_TOKEN está configurado no repositório e que o token tem permissão para publicar o pacote @digdigital/eslint-config-frontend.

Para gerar uma nova publicação:

1. Acesse a aba Actions do repositório no GitHub.
2. Selecione o workflow Create release tag.
3. Clique em Run workflow, confirme a branch master e escolha o tipo de incremento:
   • patch para correções compatíveis, por exemplo, 1.0.0 para 1.0.1;
   • minor para novas funcionalidades compatíveis, por exemplo, 1.0.0 para 1.1.0;
   • major para alterações incompatíveis, por exemplo, 1.0.0 para 2.0.0.
4. Execute o workflow e aguarde a conclusão.

O workflow calcula a próxima versão a partir do último tag semântico (vMAJOR.MINOR.PATCH), atualiza package.json e package-lock.json, executa o build, valida o conteúdo com npm pack --dry-run, publica com npm publish --access public, faz o commit da versão na master e cria o tag da release. Não é necessário alterar manualmente a versão nem executar npm publish localmente.

Após a publicação, valide a versão no npm:

npm view @digdigital/eslint-config-frontend version
npm view @digdigital/eslint-config-frontend@<versão> version

Licença

Este projeto é distribuído sob a licença ISC.