Configuração do Prettier com Claude Code

Quando Claude Code começa a editar um projeto de verdade, formatação deixa de ser detalhe visual. Uma tarefa pequena pode alterar componentes, testes, JSON, Markdown e configuração de CI ao mesmo tempo. Se indentação, aspas, quebras de linha e trailing commas aparecem misturadas no diff, a revisão fica barulhenta antes de alguém avaliar o comportamento.

Prettier é um formatador de código. Em termos simples, ele reescreve a aparência dos arquivos suportados sem decidir se a lógica está correta. Essa separação é saudável: Prettier cuida da forma, enquanto testes, TypeScript e ESLint cuidam de comportamento e regras de qualidade.

Este guia mostra uma configuração prática de Prettier para trabalhar com Claude Code. Vamos cobrir instalação local, .prettierrc, .prettierignore, scripts npm, VS Code, CI, formatação de arquivos staged e instruções de projeto para que Claude Code respeite as regras. Os exemplos foram pensados para projetos npm com JavaScript ou TypeScript.

Fluxo recomendado

Prettier funciona melhor como uma pequena barreira de qualidade em vários pontos do fluxo, não como um comando de limpeza lembrado no fim.

flowchart LR
  A["Claude Code edita arquivos"] --> B[".prettierrc define regras"]
  B --> C["VS Code formata ao salvar"]
  C --> D["npm run format:check"]
  D --> E["lint-staged formata staged files"]
  E --> F["CI verifica o PR"]

Cada camada tem uma função. .prettierrc guarda a política de formatação. .prettierignore protege arquivos gerados ou fora de escopo. Os scripts em package.json dão os mesmos comandos para pessoas, Claude Code e CI. VS Code dá feedback imediato. lint-staged limita o escopo ao commit. CI impede que código não formatado chegue à revisão.

Claude Code consegue seguir instruções em linguagem natural, mas não é bom deixar preferência de formatação só no chat. Coloque as regras no repositório e dê comandos verificáveis.

Instalar Prettier localmente

Instale Prettier como dependência de desenvolvimento do projeto. O guia oficial Prettier Install recomenda instalação local com versão exata para que todos os ambientes usem o mesmo comportamento.

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

Ao introduzir a ferramenta, rode uma primeira passada completa.

npx prettier . --write

Em um projeto existente, mantenha essa primeira passada em um commit ou pull request separado. Misturar formatação global com uma feature dificulta review e investigação de bug. Depois que a base estiver limpa, Claude Code pode fazer mudanças menores sem carregar dívida antiga de formato.

Criar .prettierrc

Prettier aceita vários formatos de configuração, como .prettierrc, prettier.config.mjs e a chave prettier em package.json. A documentação oficial de Configuration File explica que Prettier procura a configuração a partir do arquivo formatado em direção aos diretórios superiores e não usa configuração global. Isso torna o resultado reproduzível em outras máquinas.

Para começar, um .prettierrc em JSON é direto e fácil de revisar.

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "proseWrap": "always"
      }
    },
    {
      "files": ["*.yml", "*.yaml"],
      "options": {
        "singleQuote": false
      }
    }
  ]
}

printWidth é uma referência para o Prettier decidir quebras, não um limite rígido. endOfLine: "lf" reduz diferenças entre Windows, macOS, Linux e CI. trailingComma: "all" costuma deixar diffs menores quando você adiciona itens a objetos e arrays.

Se o projeto usa Tailwind CSS intensamente, avalie prettier-plugin-tailwindcss depois. Evite começar com muitos plugins. Primeiro deixe o formatador base previsível, depois adicione extensões quando houver necessidade real.

Criar .prettierignore

.prettierignore diz ao Prettier quais arquivos não devem ser reescritos. Use para artefatos de build, caches, código gerado, arquivos minificados e lockfiles mantidos por ferramentas externas.

node_modules
dist
build
coverage
.next
.nuxt
.astro
.vercel
.cache
*.min.js
package-lock.json
pnpm-lock.yaml
yarn.lock

Prettier também segue .gitignore quando roda no mesmo diretório, mas os dois arquivos têm propósitos diferentes. .gitignore decide o que o Git rastreia. .prettierignore decide o que o formatador não deve tocar. Deixar essa fronteira explícita ajuda Claude Code a respeitar o escopo.

Um erro comum é esquecer código gerado. Claude Code altera um componente pequeno e prettier . --write acaba reformatando milhares de linhas em src/generated/. Código gerado deve ser alterado pela fonte ou schema e depois regenerado, não escondido em um diff de feature.

Adicionar scripts npm

A documentação oficial do npm descreve scripts como o lugar onde o package declara comandos executáveis. Em um fluxo com Claude Code, isso cria uma linguagem comum para o agente, desenvolvedores e CI.

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

Use o comando que escreve localmente e o comando de verificação na automação.

npm run format
npm run format:check

format modifica arquivos. format:check apenas verifica se eles já estão formatados e falha quando não estão. Em CI, format:check é mais claro, porque sinaliza o problema sem reescrever código que ninguém revisou.

Configurar VS Code

Formatar ao salvar remove muito ruído antes do commit. Coloque a configuração em .vscode/settings.json para que o repositório carregue a convenção, em vez de depender das preferências pessoais de cada editor.

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true,
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[mdx]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

prettier.requireConfig é uma proteção útil. A extensão só atua em projetos que declaram configuração de Prettier. Quem alterna entre muitos repositórios evita mudanças acidentais em projetos com convenções diferentes.

Verificar em CI

Um workflow mínimo de GitHub Actions já resolve o básico.

name: format

on:
  pull_request:
  push:
    branches: [main]

jobs:
  prettier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run format:check

Quando Claude Code atualiza uma pull request, esse check elimina ruído mecânico antes da revisão humana. Para regras de qualidade, combine com o guia de ESLint com Claude Code, mas mantenha falhas de formatação e de lint como sinais separados.

Formatar apenas staged files

Em repositórios grandes, formatar tudo a cada commit pode ser lento e mexer em dívida antiga. Husky e lint-staged permitem atuar apenas nos arquivos adicionados com git add. O fluxo completo está no guia de Husky + lint-staged; aqui vai o mínimo para Prettier.

npm install --save-dev --save-exact husky lint-staged
npm pkg set scripts.prepare="husky"
npx husky init

Adicione a configuração em package.json.

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,css,md,mdx,json,yml,yaml}": "prettier --write"
  }
}

Deixe .husky/pre-commit simples.

npx lint-staged

O principal ganho é controle de escopo. Se Claude Code editou três arquivos, o pre-commit formata só esses três, sem acordar todo o histórico despadronizado do repositório.

Informar as regras ao Claude Code

As instruções do projeto devem ficar em CLAUDE.md. A documentação oficial de Claude Code memory descreve ./CLAUDE.md e ./.claude/CLAUDE.md como arquivos compartilhados para comandos, padrões de código e workflows.

## Formatting

- Read `.prettierrc` and `.prettierignore` before formatting files.
- Do not reformat unrelated files while implementing a feature.
- After changing JavaScript, TypeScript, CSS, Markdown, JSON, or YAML, run `npm run format:check`.
- Keep formatter-only changes separate from behavior changes.

Você também pode automatizar com hooks do Claude Code. O guia oficial de hooks mostra um exemplo que roda Prettier depois de ferramentas Edit ou Write.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Esse hook é útil, mas depende de jq e de comportamento de shell. Em equipes com muito Windows, comece com instruções explícitas em CLAUDE.md e exigência de npm run format:check ao fim da tarefa. Compartilhe o hook quando o ambiente estiver consistente.

Três casos de uso

Caso	Benefício do Prettier	Pedido para Claude Code
Aplicação TypeScript	Componentes, testes e tipos ficam em diff legível	Rode npm run format:check depois da mudança.
Site Astro ou MDX	Frontmatter, Markdown, code fences e JSON ficam consistentes	Confirme que os code fences de MDX continuam válidos.
Pull request em equipe	Review foca comportamento, não indentação	Não misture mudanças só de formatação com a feature.

O caso MDX é especialmente claro. Um artigo pode conter texto, frontmatter, comandos shell, JSON e JSX no mesmo arquivo. Sem Prettier, Claude Code pode gerar conteúdo correto, mas visualmente irregular. Com uma regra compartilhada, a revisão volta para precisão, estrutura e exemplos executáveis.

Erros comuns

O primeiro erro é usar npx prettier . --write sem instalar Prettier. Se a dependência não está fixa em devDependencies, npx pode buscar outra versão no futuro. Instale localmente com --save-exact.

O segundo erro é fazer ESLint e Prettier disputarem a mesma regra. Prettier formata. ESLint detecta bugs potenciais e problemas de manutenção. Se houver conflito de estilo, considere eslint-config-prettier.

O terceiro erro é formatar o repositório inteiro dentro de uma branch de feature. Se a base está inconsistente, crie primeiro uma mudança apenas de formatter. Depois peça a Claude Code para evitar formatação não relacionada.

O quarto erro é ignorar demais. Uma entrada como src/** em .prettierignore tira o código principal do padrão. Ignore gerados, caches, arquivos grandes e saídas de ferramentas externas, não o código revisado todos os dias.

CTA de monetização

Se você usa Claude Code em vários projetos, o ativo reutilizável não é apenas .prettierrc. O valor está no sistema: CLAUDE.md, comandos de verificação, checklist de review, templates de PR e regras de handoff. ClaudeCodeLab reúne esses materiais na página de produtos para transformar esta configuração em um padrão repetível.

Resumo

Prettier é uma base pequena, mas importante para trabalhar com Claude Code. Instale localmente, defina .prettierrc, proteja gerados com .prettierignore, exponha format e format:check, use VS Code para feedback imediato, verifique em CI e adicione lint-staged para limitar o escopo. Depois documente a mesma expectativa em CLAUDE.md.

Resultado testado: ao aplicar esta configuração em um pequeno projeto TypeScript e MDX, a primeira passada criou uma base limpa, npm run format:check passou de forma estável e as mudanças feitas por Claude Code ficaram mais fáceis de revisar. Os maiores ganhos vieram de ignorar saídas geradas e separar format de format:check.