Configuración de Prettier con Claude Code

Cuando empiezas a delegar cambios reales a Claude Code, el formato deja de ser un detalle estético. Una tarea pequeña puede tocar componentes, tests, archivos JSON, Markdown y configuración de CI. Si el diff mezcla cambios de indentación, comillas, saltos de línea y trailing commas, la revisión se vuelve más lenta antes de evaluar si el comportamiento está bien.

Prettier es un formateador de código. En términos simples, reescribe la forma visual de los archivos soportados sin decidir si la lógica de negocio es correcta. Esa separación es importante: Prettier debe ocuparse de la presentación, mientras que tests, TypeScript y ESLint deben ocuparse de comportamiento y reglas de calidad.

Esta guía muestra una configuración práctica de Prettier para trabajar con Claude Code. Incluye instalación local, .prettierrc, .prettierignore, scripts de npm, ajustes de VS Code, verificación en CI, formato de archivos staged y reglas para que Claude Code respete el formato del proyecto. Los ejemplos están pensados para proyectos npm con JavaScript o TypeScript.

Flujo recomendado

No trates Prettier como un comando de limpieza que alguien recuerda al final. Funciona mejor como una pequeña barrera de calidad en varias partes del flujo.

flowchart LR
  A["Claude Code edita archivos"] --> B[".prettierrc define reglas"]
  B --> C["VS Code formatea al guardar"]
  C --> D["npm run format:check"]
  D --> E["lint-staged formatea staged files"]
  E --> F["CI revisa el PR"]

Cada capa cumple una función. .prettierrc registra la política de formato. .prettierignore protege archivos generados o irrelevantes. Los scripts de package.json dan los mismos comandos a personas, Claude Code y CI. VS Code entrega feedback inmediato. lint-staged evita tocar archivos no relacionados. CI impide que código sin formatear llegue a revisión.

Claude Code puede seguir instrucciones en lenguaje natural, pero no conviene depender solo del chat. Las reglas deben vivir en el repositorio, junto con comandos verificables.

Instalar Prettier localmente

Instala Prettier como dependencia de desarrollo del proyecto. La guía oficial de Prettier Install recomienda instalarlo localmente y fijar la versión exacta para que cada entorno use el mismo comportamiento.

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

Cuando lo introduces por primera vez, ejecuta una pasada inicial.

npx prettier . --write

En un proyecto existente, esa pasada inicial debe ir en un commit o PR separado. Mezclar un formateo global con una feature vuelve el review ruidoso y hace más difícil encontrar la causa si aparece un bug. Una vez creada la línea base, Claude Code puede modificar archivos sin arrastrar deuda antigua de formato.

Crear .prettierrc

Prettier acepta varios formatos de configuración: .prettierrc, prettier.config.mjs o una clave prettier dentro de package.json. La documentación oficial de Configuration File explica que Prettier busca la configuración desde el archivo formateado hacia directorios superiores y no usa configuración global. Eso hace que el resultado sea reproducible en otras máquinas.

Para equipos que empiezan, JSON suele ser la opción más clara.

{
  "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 no es un límite duro de caracteres, sino una referencia para que Prettier decida cuándo partir líneas. endOfLine: "lf" reduce diferencias entre Windows, macOS, Linux y CI. trailingComma: "all" suele producir diffs más pequeños cuando agregas elementos a arrays u objetos.

Si tu proyecto usa Tailwind CSS, puedes evaluar prettier-plugin-tailwindcss más adelante. No lo agregues desde el primer día si todavía estás estabilizando el formatter. Primero consigue una base predecible; luego suma plugins que resuelvan un problema real.

Crear .prettierignore

.prettierignore le dice a Prettier qué archivos no debe tocar. Úsalo para artefactos de build, caches, archivos generados, minificados y lockfiles mantenidos por herramientas externas.

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

Prettier también respeta .gitignore cuando se ejecuta desde el mismo directorio, pero no son lo mismo. .gitignore decide qué entra en Git; .prettierignore decide qué no debe reescribirse. Mantener esa lista explícita ayuda a Claude Code a no cruzar límites que para el equipo son obvios.

Un fallo común es olvidar código generado. Claude Code puede cambiar un componente pequeño y, al correr prettier . --write, terminar modificando miles de líneas bajo src/generated/. Si el archivo se genera, corrige el schema o la fuente y vuelve a generarlo. No uses Prettier para maquillar output generado.

Añadir scripts de npm

La documentación oficial de npm define scripts como el lugar donde un paquete declara comandos ejecutables. En un flujo con Claude Code, esto permite que el agente, los desarrolladores y CI usen los mismos nombres.

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

Usa el comando de escritura en local y el de chequeo en automatización.

npm run format
npm run format:check

format modifica archivos. format:check solo verifica que ya estén formateados y falla si no lo están. Por eso format:check encaja mejor en CI: da una señal clara sin reescribir código que nadie ha revisado.

Configurar VS Code

Formatear al guardar reduce el ruido antes de llegar al commit. Coloca la configuración en .vscode/settings.json para que el repositorio defina el comportamiento, no las preferencias personales 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 es una protección útil. Hace que la extensión solo actúe en proyectos que declaran configuración de Prettier. Si trabajas con muchos repositorios, evita cambios accidentales en proyectos con convenciones distintas.

Revisar formato en CI

Este workflow de GitHub Actions es suficiente para empezar.

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

Cuando Claude Code modifica un PR, este check evita que un reviewer pierda tiempo en diferencias mecánicas. Si también quieres reglas de calidad, combínalo con la guía de ESLint con Claude Code, pero procura que fallos de formato y fallos de lint sean señales separadas.

Formatear solo staged files

En repositorios grandes, formatear todo en cada commit puede ser lento y generar diffs innecesarios. Husky y lint-staged permiten actuar solo sobre archivos ya añadidos con git add. El flujo completo está en la guía de Husky + lint-staged, pero para Prettier basta con esto.

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

Añade la configuración en package.json.

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

Mantén .husky/pre-commit simple.

npx lint-staged

El beneficio principal es el alcance. Si Claude Code toca tres archivos, el pre-commit formatea esos tres archivos, no toda la deuda histórica del repositorio.

Indicar las reglas a Claude Code

Las instrucciones del proyecto deben estar en CLAUDE.md. La documentación oficial de Claude Code memory describe ./CLAUDE.md y ./.claude/CLAUDE.md como archivos compartidos para comandos, estándares de código, arquitectura y flujos de trabajo.

## 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.

También puedes automatizar con hooks de Claude Code. La guía oficial de hooks muestra un ejemplo que ejecuta Prettier después de herramientas Edit o Write.

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

Ese hook es útil, pero depende de jq y del entorno de shell. En equipos que usan mucho Windows, puede ser más sólido empezar con instrucciones claras en CLAUDE.md y exigir npm run format:check al cerrar cada tarea. Después, cuando el entorno esté unificado, puedes compartir el hook.

Tres casos de uso

Caso	Beneficio	Prompt para Claude Code
Aplicación TypeScript	Componentes, tests y tipos quedan en un diff legible	Ejecuta npm run format:check después del cambio.
Sitio Astro o MDX	Frontmatter, Markdown, code fences y JSON quedan consistentes	Verifica que los code fences de MDX sigan válidos.
Pull requests de equipo	La revisión se centra en comportamiento, no en indentación	No mezcles cambios solo de formato con la feature.

El caso MDX es especialmente visible. Un artículo puede incluir texto, frontmatter, comandos de shell, JSON y JSX en el mismo archivo. Sin Prettier, Claude Code puede producir contenido correcto pero visualmente irregular. Con una regla compartida, la revisión vuelve a enfocarse en exactitud, estructura y ejemplos que funcionen.

Errores comunes

El primer error es usar npx prettier . --write sin instalar Prettier. Si no está en devDependencies, npx puede descargar temporalmente una versión diferente. Fija la versión local con --save-exact.

El segundo error es hacer que ESLint y Prettier compitan. Prettier formatea. ESLint debe detectar problemas de calidad o posibles bugs. Si hay reglas de estilo que chocan, revisa eslint-config-prettier.

El tercer error es formatear todo el repositorio dentro de una rama de feature. Si la base está desordenada, crea primero un cambio solo de formatter. Luego pide a Claude Code que no toque archivos no relacionados.

El cuarto error es ignorar demasiado. Una entrada como src/** en .prettierignore anula el valor del formatter. Ignora generados, caches, archivos enormes o controlados por otras herramientas, no el código principal.

CTA de monetización

Si usas Claude Code en varios proyectos, el activo reutilizable no es solo .prettierrc. Lo valioso es el sistema completo: CLAUDE.md, comandos de verificación, checklist de review, plantillas de PR y notas de handoff. ClaudeCodeLab reúne estos materiales en la página de productos para convertir esta configuración en un estándar repetible.

Resumen

Prettier es una base pequeña pero importante para trabajar con Claude Code. Instálalo localmente, define .prettierrc, protege archivos generados con .prettierignore, expón format y format:check, usa VS Code para feedback inmediato, revisa en CI y agrega lint-staged cuando quieras limitar el alcance al commit. Luego documenta la expectativa en CLAUDE.md.

Resultado probado: al aplicar esta configuración en un proyecto pequeño de TypeScript y MDX, la primera pasada dejó una base limpia, npm run format:check pasó de forma estable y los cambios generados por Claude Code fueron más fáciles de revisar. Lo que más ayudó fue separar format de format:check e ignorar outputs generados.