Prettier no Node.js

Atualizado em: 8 de setembro de 2026

Estação de trabalho usada no desenvolvimento de aplicações Node.js

O Prettier no Node.js automatiza a formatação do código e elimina discussões repetitivas sobre espaços, quebras de linha, aspas e indentação. Em vez de cada pessoa aplicar um estilo diferente, o projeto fixa uma versão da ferramenta, define poucas opções e verifica o resultado no editor, no pre-commit e na integração contínua.

Prettier não substitui ESLint. O formatter reorganiza a apresentação do código; o linter encontra problemas, padrões perigosos e regras de qualidade. Quando as responsabilidades são separadas, o projeto evita configurações conflitantes e mantém uma experiência previsível.

Neste guia, você aprenderá a instalar Prettier com versão exata, criar arquivos de configuração e ignore, formatar JavaScript, TypeScript, JSON e Markdown, integrar com ESLint, editor, lint-staged e GitHub Actions, além de migrar projetos grandes sem poluir o histórico.

Por que usar Prettier?

Formatação manual cria diferenças sem valor funcional. Um arquivo pode ser reindentado inteiro por uma pequena alteração, aumentando conflitos e dificultando revisão. Prettier aplica uma saída determinística para a mesma versão, configuração e conteúdo.

A documentação oficial de instalação do Prettier recomenda instalar uma versão exata localmente. Até uma atualização de patch pode mudar a saída, então depender de uma instalação global ou de download temporário pelo npx gera alterações inesperadas.

Instalação exata

npm install --save-dev --save-exact prettier

O --save-exact grava uma versão fixa no package.json. O lockfile mantém a árvore reproduzível.

Configuração mínima

Crie .prettierrc:

{}

Mesmo vazio, o arquivo informa a editores e ferramentas que o projeto utiliza Prettier.

Configuração JavaScript

Também é possível usar prettier.config.mjs:

/** @type {import('prettier').Config} */
const config = {
  printWidth: 100,
  singleQuote: true,
  trailingComma: 'all',
  semi: true
};

export default config;

Use poucas opções. A principal vantagem do Prettier é reduzir escolhas estilísticas, não recriar um formatter personalizado.

Arquivo .prettierignore

dist
coverage
node_modules
.cache
*.min.js
generated

Prettier também considera padrões do .gitignore em determinados fluxos, mas um arquivo dedicado deixa claro o que não deve ser formatado.

Scripts do package.json

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

--write modifica arquivos. --check apenas valida e retorna status de erro quando existe diferença.

Formatando o projeto

npm run format

Para um diretório específico:

npx prettier src test --write

Para apenas um arquivo:

npx prettier src/server.js --write

Verificação no CI

- name: Check formatting
  run: npm run format:check

O CI não deve executar --write e esconder a falha. Ele deve avisar que o código precisa ser formatado. Consulte CI para Node.js com GitHub Actions.

Prettier e ESLint

Instale a configuração que desativa regras estilísticas incompatíveis:

npm install --save-dev eslint-config-prettier

Com Flat Config:

import eslintConfigPrettier from 'eslint-config-prettier';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  // outras configurações
  eslintConfigPrettier
]);

Coloque a configuração do Prettier perto do final para desativar regras conflitantes. O artigo ESLint Flat Config no Node.js apresenta a estrutura completa.

Não execute Prettier como regra ESLint

Plugins que transformam diferenças de formatação em erros do ESLint podem ser úteis em alguns ambientes, mas normalmente tornam lint mais lento e misturam responsabilidades. Uma etapa prettier --check separada produz diagnóstico mais claro.

Integração com editor

Instale a extensão oficial e configure o editor para usar a versão local do projeto. No VS Code:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true
}

requireConfig evita formatar projetos que não adotaram Prettier. Compartilhe configurações de workspace apenas quando forem úteis para toda a equipe.

Formatar apenas arquivos alterados

Instale Husky e lint-staged:

npm install --save-dev husky lint-staged
npx husky init

No package.json:

{
  "lint-staged": {
    "**/*": "prettier --write --ignore-unknown"
  }
}

No hook:

npx lint-staged

--ignore-unknown evita falha em extensões que o Prettier não reconhece.

Ordem com ESLint

Quando lint-staged executa as duas ferramentas, rode ESLint antes de Prettier:

{
  "lint-staged": {
    "*.{js,mjs,cjs,ts,mts,cts}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

O formatter deve ser a última etapa que altera estilo.

JavaScript e TypeScript

Prettier entende sintaxe moderna e TypeScript, mas não realiza typecheck. Um arquivo pode estar perfeitamente formatado e conter erro de tipo. Mantenha tsc --noEmit ou build no CI.

Para conhecer a linguagem, consulte O que é TypeScript.

JSON, YAML e Markdown

A ferramenta também formata arquivos de configuração:

npx prettier "**/*.{json,yml,yaml,md}" --write

Revise arquivos gerados ou documentos cujo layout precisa ser preservado e adicione-os ao ignore quando necessário.

Ignorando trechos

Para um nó específico:

// prettier-ignore
const matrix = [
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]
];

Use prettier-ignore somente quando o formato manual transmite significado ou existe incompatibilidade real. Exceções frequentes indicam que o arquivo talvez não deva ser formatado.

Fim de linha

Projetos com Windows, Linux e macOS devem normalizar linhas:

{
  "endOfLine": "lf"
}

Combine com .gitattributes:

* text=auto eol=lf

Scripts específicos de Windows podem exigir exceção.

Print width

printWidth orienta a quebra, mas não é um limite rígido. URLs, strings longas e estruturas específicas podem ultrapassar o valor. Não use o formatter como substituto para regra de complexidade ou design.

Aspas e ponto e vírgula

Escolha singleQuote e semi uma vez e evite debates contínuos. Essas opções raramente afetam qualidade funcional. O valor do padrão compartilhado é maior do que a preferência individual.

Plugins

Plugins adicionam suporte ou ordenação para tecnologias específicas. Instale apenas os necessários, fixe versões e confira sua manutenção. Plugins executam código durante formatação e fazem parte da cadeia de dependências.

Configuração compartilhada

Uma organização pode publicar um pacote:

export default {
  printWidth: 100,
  singleQuote: true,
  trailingComma: 'all'
};

No projeto:

export { default } from '@empresa/prettier-config';

Permita poucas extensões locais para manter consistência sem bloquear necessidades específicas.

Migração de projeto grande

Formatar todo o repositório em uma mudança junto com alterações funcionais dificulta revisão. Faça:

fixe a versão;
crie configuração e ignore;
gere um commit somente de formatação;
não inclua mudanças funcionais;
avise a equipe antes de branches longas;
ative check no CI depois do merge;
configure editor e hook.

Git blame

Uma reformatação ampla altera autores no histórico. Git permite ignorar revisões conhecidas em blame por meio de arquivo de commits ignorados. Documente o hash do commit de formatação.

Arquivos gerados

Não formate build, cobertura, código gerado por OpenAPI ou arquivos de vendors. A fonte deve ser formatada antes da geração; o resultado segue a ferramenta produtora.

Veja OpenAPI com Node.js.

Prettier no monorepo

Mantenha uma configuração na raiz sempre que possível. Em workspaces:

prettier "packages/**/*.{js,ts,json,md}" --check

Use ignores para outputs individuais. Configurações diferentes por pacote aumentam conflitos ao mover código.

Desempenho

Em repositórios grandes, evite incluir node_modules, builds e caches. Use lint-staged no fluxo diário e --check completo no CI. Não dependa apenas do hook, porque ele pode ser ignorado localmente.

Atualizações

Uma atualização pode reformar muitos arquivos. Faça upgrade em pull request dedicado:

atualize a versão exata;
execute formatação;
revise changelog;
confirme plugins;
execute lint, testes e build;
mantenha o commit isolado.

Erros comuns

Versão global: membros geram saídas diferentes.
npx sem dependência: baixa versão mais recente.
Sem ignore: build e cobertura são alterados.
ESLint estilístico: conflitos e mensagens duplicadas.
CI com –write: problema é escondido.
Formatação com feature: revisão fica poluída.
Hook como única proteção: pode ser pulado.
Plugin não fixado: saída muda inesperadamente.

Configuração recomendada

// prettier.config.mjs
export default {
  printWidth: 100,
  singleQuote: true,
  trailingComma: 'all',
  semi: true,
  endOfLine: 'lf'
};

# .prettierignore
dist
coverage
.cache
generated
*.min.js

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

Conclusão

O Prettier no Node.js reduz ruído de revisão e mantém arquivos consistentes. O fluxo mais confiável fixa uma versão exata, usa configuração pequena, exclui artefatos e executa --check no CI.

Separe formatação de lint, configure o editor para usar a versão local e adicione lint-staged apenas como feedback rápido. Assim, a equipe gasta menos tempo discutindo estilo e mais tempo revisando comportamento, segurança e arquitetura.