Prettier no Node.js

Prettier é um formatador opinativo que transforma código em um estilo consistente. Em projetos Node.js, ele reduz discussões sobre espaços, quebras de linha, aspas, vírgulas finais e indentação. O objetivo não é encontrar bugs, mas garantir que arquivos equivalentes sejam apresentados da mesma forma em qualquer editor, sistema operacional ou pipeline.

Ao contrário de uma regra de lint tradicional, Prettier analisa o código, constrói uma representação sintática e imprime novamente o arquivo. Isso significa que ele pode reorganizar várias linhas de uma só vez, mantendo o comportamento do programa.

Instalação local

Instale como dependência de desenvolvimento:

npm install -D prettier

Fixar a versão no lockfile é importante. Uma atualização do formatador pode alterar milhares de linhas, então não dependa de uma instalação global diferente em cada máquina.

Adicione scripts:

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

Arquivo de configuração

Crie prettier.config.mjs em um projeto ESM:

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

export default config;

Também são aceitos arquivos como .prettierrc, .prettierrc.json, prettier.config.js e configurações no package.json. Um arquivo JavaScript permite comentários e composição, mas uma configuração simples em JSON pode ser suficiente.

Filosofia de poucas opções

Prettier oferece poucas opções de propósito. A intenção é evitar que cada equipe recrie um guia de estilo inteiro. Configure apenas o necessário e aceite o restante dos padrões. Quanto mais opções específicas, maior a diferença entre projetos e menor o benefício de um formatador opinativo.

printWidth não é limite rígido

printWidth indica o tamanho aproximado desejado para as linhas. Não funciona como a regra max-len do ESLint. Prettier pode produzir linhas maiores quando não existe uma quebra adequada e pode quebrar antes do limite quando a estrutura fica mais legível.

Evite aumentar para valores extremos apenas para impedir quebras. O resultado tende a ficar difícil de revisar em telas divididas e diffs.

Semicolons e ASI

Com semi: true, Prettier adiciona ponto e vírgula. Com false, ainda insere semicolons onde são necessários para evitar problemas de Automatic Semicolon Insertion.

const resultado = calcular()
;[1, 2, 3].forEach(processar)

Escolha uma preferência, mas deixe Prettier cuidar dos casos perigosos.

Aspas e propriedades

singleQuote: true prefere aspas simples em JavaScript, mas Prettier escolhe a alternativa que exige menos escapes. quoteProps controla quando propriedades de objetos permanecem entre aspas.

const mensagem = "O usuário disse 'olá'";

Mesmo com aspas simples configuradas, a forma acima pode ser mantida por ser mais simples.

Vírgulas finais

O padrão moderno é trailingComma: 'all', adicionando vírgulas onde a sintaxe permite:

const usuario = {
  id: 10,
  nome: 'Ana',
  ativo: true,
};

Isso melhora diffs, porque adicionar uma nova linha não exige modificar a anterior.

Fim de linha consistente

Use endOfLine: 'lf' e complemente com .gitattributes:

* text=auto eol=lf

Essa configuração evita diffs gigantes causados pela conversão entre LF e CRLF em equipes que usam Windows, Linux e macOS.

Ignorando arquivos

Crie .prettierignore:

node_modules/
dist/
coverage/
.cache/
*.min.js
package-lock.json

Ignorar lockfiles nem sempre é necessário, pois Prettier entende vários formatos, mas muitas equipes preferem deixar o gerenciador controlar o arquivo. Não ignore código-fonte sem um motivo claro.

Ignorando trechos específicos

Para um nó sintático específico:

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

Use exceções com moderação. Muitas diretivas indicam que o arquivo ou a estrutura precisa ser repensado.

Integração com editores

Configure o editor para usar a versão local e formatar ao salvar. No VS Code:

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

requireConfig evita formatar arquivos de projetos que não adotaram Prettier.

Prettier e ESLint

Prettier cuida de formatação; ESLint encontra padrões problemáticos e aplica regras de qualidade. Evite configurar regras estilísticas conflitantes nos dois.

Instale eslint-config-prettier para desativar regras de lint que entram em conflito:

npm install -D eslint-config-prettier

Em Flat Config:

import eslintConfigPrettier from 'eslint-config-prettier';

export default [
  // outras configurações
  eslintConfigPrettier,
];

Coloque a configuração no final para que ela desative conflitos anteriores.

Evite executar Prettier como regra do ESLint

Plugins que transformam diferenças de formatação em erros de ESLint podem tornar o lint mais lento e gerar mensagens menos claras. Em muitos projetos, é melhor executar:

npm run lint
npm run format:check

Separar responsabilidades simplifica diagnóstico e permite paralelizar tarefas no CI.

Prettier em pre-commit

Para formatar apenas arquivos alterados, use lint-staged:

npm install -D husky lint-staged
npx husky init

{
  "lint-staged": {
    "*.{js,mjs,cjs,ts,tsx,json,md,yml,yaml}": "prettier --write"
  }
}

O hook melhora a experiência, mas não substitui o CI. Hooks podem ser ignorados ou não instalados.

Verificação no CI

- run: npm ci
- run: npm run format:check
- run: npm run lint

--check não altera arquivos. Ele retorna código de saída diferente de zero quando encontra formatação incorreta.

Adoção gradual

Em um projeto antigo, formatar tudo de uma vez pode destruir o histórico de git blame. Existem três estratégias:

• formatar todo o repositório em um commit exclusivo;
• formatar diretórios aos poucos;
• usar pragmas para formatar apenas arquivos marcados.

Com --require-pragma, Prettier processa arquivos que começam com @format ou @prettier. --insert-pragma pode adicionar a marca durante a migração.

Formatando via stdin

Ao enviar conteúdo por pipe, informe o caminho para que o parser seja inferido:

cat exemplo.ts | prettier --stdin-filepath exemplo.ts

Sem o caminho, Prettier pode não saber se o conteúdo é TypeScript, CSS, JSON ou outro formato.

Overrides por tipo de arquivo

export default {
  singleQuote: true,
  overrides: [
    {
      files: '*.json',
      options: {
        tabWidth: 2,
      },
    },
    {
      files: '*.md',
      options: {
        proseWrap: 'preserve',
      },
    },
  ],
};

Use overrides apenas quando o formato exige uma decisão específica.

Plugins

Plugins adicionam suporte a linguagens ou ordenações específicas. Instale localmente e declare quando necessário:

export default {
  plugins: ['prettier-plugin-packagejson'],
};

Revise a origem e manutenção do plugin. Ele executa código durante a formatação e faz parte da cadeia de ferramentas.

API programática

Prettier pode ser usado em scripts:

import prettier from 'prettier';

const configuracao = await prettier.resolveConfig('src/app.js');
const formatado = await prettier.format(codigo, {
  ...configuracao,
  parser: 'babel',
});

Prefira resolver a configuração do projeto em vez de duplicar opções dentro do script.

Monorepos

Uma configuração raiz mantém todos os workspaces consistentes. Pacotes podem ter arquivos locais apenas quando realmente precisam divergir. Para configurações compartilhadas entre repositórios, publique um pacote:

import config from '@empresa/prettier-config';
export default config;

Atualizações de versão

Atualize Prettier em um pull request dedicado. Execute prettier . --write, revise o diff e não misture mudanças funcionais. Assim, a equipe diferencia alterações automáticas de mudanças de lógica.

Fluxo recomendado

Instale localmente, mantenha uma configuração pequena, use .prettierignore, configure o editor, formate arquivos alterados no pre-commit e valide tudo no CI. Combine com ESLint Flat Config no Node.js, monorepos em npm Workspaces no Node.js, versões de ferramentas com Corepack no Node.js e pipelines descritos em GitHub Actions no Node.js.

Consulte as opções oficiais do Prettier e o guia oficial para executar Prettier no CI.