Como Fazer Lint do seu CSS com Stylelint

CSS bagunçado é fácil de escrever e difícil de manter. Propriedades escritas incorretamente, seletores duplicados e convenções inconsistentes passam pela revisão de código e se acumulam como dívida técnica. O Stylelint resolve isso ao detectar erros e impor padrões automaticamente — antes que cheguem à produção.

Este guia cobre tudo o que você precisa para fazer o linting de CSS com Stylelint funcionar no seu projeto hoje.

O Que é o Stylelint e Por Que Ele Pertence ao Seu Fluxo de Trabalho?

O Stylelint é um linter de CSS com mais de 100 regras integradas, utilizado por equipes do Google e do GitHub. Ele analisa estaticamente seus arquivos CSS e relata problemas — sintaxe inválida, propriedades desconhecidas, seletores duplicados e violações de convenção — sem executar o código.

Uma distinção importante: o Stylelint cuida da qualidade do código, não da formatação. Ele não vai brigar com o Prettier por espaçamento ou ponto e vírgula. As duas ferramentas são complementares. O Prettier formata, enquanto o Stylelint impõe correção e consistência. Use ambos.

Instalando o Stylelint: Duas Maneiras de Começar

O Stylelint requer uma versão moderna do Node.js (Node 20.19.0 ou mais recente em versões atuais), portanto certifique-se de que seu ambiente esteja atualizado.

Opção 1: Configuração Automatizada (Recomendada)

A forma mais rápida de fazer lint de CSS com o Stylelint é o comando create:

npm create stylelint@latest

Isso gera um arquivo de configuração e instala o stylelint-config-standard automaticamente. Também funciona com pnpm, Yarn e Bun:

pnpm create stylelint
bun create stylelint

Opção 2: Configuração Manual do Stylelint

Se preferir controle total, instale as dependências você mesmo:

npm add -D stylelint stylelint-config-standard

Em seguida, crie um arquivo stylelint.config.mjs na raiz do seu projeto:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"]
};

A extensão .mjs usa ESM — o formato moderno de módulos. O Stylelint suporta configuração ESM, que é a abordagem recomendada em configurações atuais.

Executando o Stylelint nos Seus Arquivos CSS

Uma vez instalado, execute o Stylelint em todos os arquivos CSS:

npx stylelint "**/*.css"

Você verá uma saída como esta para quaisquer violações:

src/main.css
  12:3  ✖  Unexpected duplicate selector ".btn"   no-duplicate-selectors
  24:5  ✖  Unknown property "colour"              property-no-unknown

Para corrigir automaticamente o que for possível, adicione a flag --fix:

npx stylelint "**/*.css" --fix

Nem toda regra suporta correção automática, mas muitas suportam. A flag --fix aplica correções seguras quando possível, mas não resolverá todos os problemas.

Configurando Regras de Linting CSS do Stylelint

O stylelint-config-standard é uma base sólida. Você pode estendê-lo e sobrescrever regras específicas na sua configuração:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"],
  rules: {
    "color-no-invalid-hex": true,
    "unit-no-unknown": true,
    "selector-id-pattern": null  // desativa uma regra
  }
};

As regras aceitam true para ativar, null para desativar, ou um array para configurar a severidade:

"color-no-invalid-hex": [true, { severity: "warning" }]

Isso é útil ao introduzir o Stylelint em uma base de código existente — avisos permitem auditar problemas sem bloquear builds imediatamente.

Adicionando um Script de Lint ao package.json

Integre o Stylelint ao seu fluxo de trabalho com um script npm:

{
  "scripts": {
    "lint:css": "stylelint \"**/*.css\""
  }
}

Execute-o com npm run lint:css. A partir daqui, você pode integrá-lo ao seu pipeline de CI ou a hooks de pre-commit usando lint-staged e Husky.

Boas Práticas de Linting CSS

• Comece com o stylelint-config-standard — ele reflete as melhores práticas atuais de CSS e é mantido ativamente.
• Use avisos antes de erros ao adotar o Stylelint em código legado.
• Ignore arquivos gerados adicionando um arquivo .stylelintignore (semelhante ao .gitignore).
• Combine com o Prettier — não tente usar o Stylelint para formatação.
• Execute no CI — linting feito apenas em máquinas locais acaba sendo ignorado.

Conclusão

O Stylelint leva cerca de cinco minutos para ser configurado e compensa imediatamente em erros detectados e código consistente. Instale-o, estenda o stylelint-config-standard, adicione um script e execute-o. Essa é toda a configuração. Tudo o mais — regras personalizadas, suporte a SCSS, integração com IDE — é construído sobre essa base.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.