Formatação de Código JavaScript: Ferramentas e Padrões

Abra qualquer pull request em que metade do diff são mudanças de espaçamento e você vai sentir a dor na hora. Inconsistências de formatação desperdiçam tempo, poluem revisões de código e criam conflitos de merge que não têm nada a ver com lógica. A solução é direta: escolha um padrão de formatação, automatize a aplicação e nunca mais pense nisso.

Este guia percorre as ferramentas e os padrões que tornam a formatação de JavaScript um problema resolvido.

Por Que a Formatação Consistente Importa

Formatação não tem a ver com estética — tem a ver com velocidade da equipe. Quando cada desenvolvedor usa indentação, posição de colchetes e comprimento de linha diferentes, três coisas acontecem:

Revisões de código ficam lentas. Revisores gastam energia mental interpretando formatação desconhecida em vez de avaliar a lógica. Uma função com aparência diferente de tudo no repositório chama atenção pelos motivos errados.

Conflitos de merge se multiplicam. O Desenvolvedor A reformata um arquivo com tabs, o Desenvolvedor B usa espaços, e agora o Git mostra cada linha como alterada. A correção de bug de três linhas fica enterrada.

A carga cognitiva aumenta. Alternar entre arquivos com estilos diferentes força seu cérebro a reinterpretar a estrutura constantemente. Formatação consistente permite ler código como texto corrido — seus olhos já sabem para onde olhar.

A solução não é discutir qual estilo é melhor. É escolher um e automatizar.

Guias de Estilo JavaScript Populares

Antes de escolher ferramentas, vale entender os principais guias de estilo que moldaram as convenções de formatação JavaScript.

Airbnb Style Guide

O guia de estilo JavaScript mais amplamente adotado. Ele exige ponto e vírgula, prefere aspas simples, requer vírgulas finais em construções multilinhas e usa indentação de 2 espaços. A configuração de ESLint (eslint-config-airbnb) agrupa centenas de regras cobrindo tanto formatação quanto qualidade de código.

// Estilo Airbnb
const getUserData = (userId) => {
  const user = findUser(userId);
  return {
    name: user.name,
    email: user.email,
  };
};

Standard Style

Adota a abordagem oposta em relação ao ponto e vírgula — sem ponto e vírgula, nunca. Usa indentação de 2 espaços e aspas simples. O pacote standard inclui seu próprio linter, então você não precisa de uma configuração separada de ESLint.

// Estilo Standard
const getUserData = (userId) => {
  const user = findUser(userId)
  return {
    name: user.name,
    email: user.email
  }
}

Google Style Guide

Similar ao Airbnb, mas com algumas diferenças nos requisitos de JSDoc e convenções de nomenclatura. Usa indentação de 2 espaços, exige ponto e vírgula e prefere aspas simples.

Cada um desses guias de estilo tem seus prós e contras. O importante é a consistência, não qual deles você escolhe. E, cada vez mais, equipes pulam o debate inteiro deixando o Prettier decidir.

Prettier: O Formatador Opinativo

O Prettier transformou a formatação JavaScript ao eliminar a maioria das decisões. Ele analisa seu código em uma AST (Abstract Syntax Tree) e o reescreve de acordo com suas próprias regras. Você não configura cada escolha de formatação individualmente — define algumas opções de alto nível e o Prettier cuida do resto.

Instalação

npm install --save-dev prettier

Crie um arquivo de configuração .prettierrc:

{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always"
}

Opções de Configuração Principais

printWidth (padrão: 80) — O comprimento de linha em que o Prettier quebra o código. Não é um limite rígido — o Prettier usa como referência para decidir quando dividir expressões em múltiplas linhas. Definir como 100 ou 120 é comum para equipes com monitores largos.

semi (padrão: true) — Se deve adicionar ponto e vírgula no final das declarações. Defina como false se preferir o estilo Standard.

singleQuote (padrão: false) — Usa aspas simples em vez de aspas duplas. A maioria dos desenvolvedores JavaScript prefere aspas simples, tornando true a configuração mais comum.

trailingComma (padrão: "all") — Adiciona vírgulas finais onde for válido. Isso produz diffs mais limpos no Git porque adicionar um novo item a uma lista mostra apenas uma linha alterada em vez de duas.

// Sem vírgulas finais — adicionar "d" altera duas linhas
const items = [
-  "a",
-  "b",
-  "c"
+  "a",
+  "b",
+  "c",
+  "d"
];

// Com vírgulas finais — adicionar "d" altera uma linha
const items = [
  "a",
  "b",
  "c",
+  "d",
];

arrowParens (padrão: "always") — Se deve envolver um único parâmetro de arrow function em parênteses. "always" significa (x) => x, "avoid" significa x => x.

Executando o Prettier

# Formatar todos os arquivos
npx prettier --write .

# Verificar sem modificar
npx prettier --check .

# Formatar tipos de arquivo específicos
npx prettier --write "src/**/*.{js,jsx,ts,tsx}"

Adicione um arquivo .prettierignore para ignorar arquivos gerados:

node_modules
dist
build
coverage
*.min.js

Se você trabalha com JavaScript minificado, nosso Code Minifier lida com a minificação corretamente — nunca edite código minificado manualmente.

ESLint: Além da Formatação

O ESLint tem um propósito diferente do Prettier. Enquanto o Prettier cuida da aparência do código, o ESLint detecta como o código se comporta. As regras do ESLint se dividem em duas categorias:

Regras de formatação — indentação, espaçamento, posição de colchetes. Essas se sobrepõem ao Prettier e geralmente devem ser desabilitadas quando se usam ambas as ferramentas.

Regras de qualidade de código — variáveis não utilizadas, código inalcançável, coerção implícita de tipos, tratamento de erros ausente. É aqui que o ESLint brilha.

Configuração Recomendada

npm install --save-dev eslint @eslint/js

Um eslint.config.js mínimo:

import js from '@eslint/js';

export default [
  js.configs.recommended,
  {
    rules: {
      'no-unused-vars': 'warn',
      'no-console': 'warn',
      'eqeqeq': 'error',
      'no-implicit-coercion': 'error',
    },
  },
];

Para projetos TypeScript, adicione typescript-eslint:

npm install --save-dev typescript-eslint

import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  js.configs.recommended,
  ...tseslint.configs.recommended,
);

Integração Prettier + ESLint

Executar ambas as ferramentas sem coordenação gera conflitos — as regras de formatação do ESLint brigam com a saída do Prettier. A solução é o eslint-config-prettier, que desabilita todas as regras do ESLint que conflitam com o Prettier.

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

import js from '@eslint/js';
import prettierConfig from 'eslint-config-prettier';

export default [
  js.configs.recommended,
  prettierConfig,
  {
    rules: {
      // Apenas regras de qualidade de código aqui
      'no-unused-vars': 'warn',
      'eqeqeq': 'error',
    },
  },
];

Com essa configuração, o Prettier é dono da formatação e o ESLint é dono da qualidade de código. Sem conflitos, sem confusão.

EditorConfig para Consistência entre Editores

Nem todo mundo na sua equipe usa o mesmo editor. O EditorConfig fornece uma base que funciona no VS Code, WebStorm, Vim, Sublime Text e na maioria dos outros editores.

Crie um arquivo .editorconfig na raiz do seu projeto:

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

O EditorConfig cuida do básico — indentação, finais de linha, espaços em branco à direita — antes mesmo do Prettier rodar. Isso evita o problema comum de um desenvolvedor Windows introduzir finais de linha \r\n em um projeto baseado em Unix.

Git Hooks com Husky e lint-staged

Formatação automatizada só funciona se de fato for executada. Depender de desenvolvedores lembrarem de rodar npx prettier --write antes de cada commit não escala. Git hooks resolvem isso.

Configuração

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

Adicione ao package.json:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint --fix"
    ],
    "*.{json,md,css}": [
      "prettier --write"
    ]
  }
}

Atualize o hook de pre-commit do Husky (.husky/pre-commit):

npx lint-staged

Agora, cada commit formata automaticamente os arquivos em staging e executa correções do ESLint. Os desenvolvedores nunca precisam pensar em formatação — simplesmente acontece.

Esse é o padrão ouro para projetos em equipe: Prettier formata, ESLint encontra bugs, Husky garante ambos em cada commit.

O Debate do Ponto e Vírgula

Nenhuma discussão sobre formatação JavaScript estaria completa sem a questão do ponto e vírgula. Eis a resposta prática: não importa, desde que sua equipe seja consistente.

Pró-ponto e vírgula: A terminação explícita de declarações evita casos extremos do ASI (Automatic Semicolon Insertion). Os guias de estilo Airbnb e Google os exigem.

Sem ponto e vírgula: O ASI do JavaScript cuida da terminação automaticamente. O código fica mais limpo com menos ruído visual. O guia de estilo Standard os omite.

As armadilhas do ASI sobre as quais as pessoas alertam — como linhas começando com ( ou [ — são capturadas pela regra no-unexpected-multiline do ESLint. Na prática, não usar ponto e vírgula com linting adequado é perfeitamente seguro.

Escolha um, configure a opção semi do Prettier e siga em frente. O Prettier vai adicionar ou remover consistentemente de qualquer forma.

Tabs vs Espaços em JavaScript

O ecossistema JavaScript usa espaços de forma esmagadora — especificamente, indentação de 2 espaços. Isso não é universal (Go usa tabs, Python usa 4 espaços), mas em JavaScript é a convenção predominante.

Por que 2 espaços? Os padrões de callbacks aninhados e métodos encadeados do JavaScript criam indentação profunda rapidamente. Dois espaços mantêm código profundamente aninhado legível sem empurrá-lo para fora da borda direita da tela.

Por que não tabs? Tabs permitem que cada desenvolvedor defina sua própria largura de exibição, o que parece bom mas significa que o alinhamento do código quebra entre editores. Com espaços, o que você vê é o que todos veem.

Configure isso uma vez no Prettier (tabWidth: 2, useTabs: false) e no EditorConfig (indent_style = space, indent_size = 2), e está resolvido.

Armadilhas Comuns de Formatação

Arrow Functions Inconsistentes

// Inconsistente — evite isso
const double = x => x * 2;
const add = (a, b) => a + b;
const greet = (name) => {
  return `Hello, ${name}`;
};

// Consistente — Prettier com arrowParens: "always"
const double = (x) => x * 2;
const add = (a, b) => a + b;
const greet = (name) => {
  return `Hello, ${name}`;
};

Estilo de Desestruturação de Objetos

// Comprimido — difícil de ler
const {name,email,role} = user;

// Formatado — Prettier cuida disso automaticamente
const { name, email, role } = user;

// Multilinha para muitas propriedades
const {
  name,
  email,
  role,
  department,
  startDate,
} = user;

Organização de Declarações de Import

O Prettier não ordena imports — isso é uma preocupação de qualidade de código, não de formatação. Use eslint-plugin-import ou o plugin simple-import-sort:

// Imports organizados
import React from 'react';
import { useState, useEffect } from 'react';

import { Button } from '@/components/Button';
import { Modal } from '@/components/Modal';

import { formatDate } from '../utils/dates';
import { validateEmail } from '../utils/validation';

Expressões Ternárias Longas

// Ilegível em uma única linha
const label = isAdmin ? 'Admin Dashboard' : hasEditPermission ? 'Editor View' : 'Read Only';

// Prettier reformata para multilinha legível
const label = isAdmin
  ? 'Admin Dashboard'
  : hasEditPermission
    ? 'Editor View'
    : 'Read Only';

Configurando um Novo Projeto

Aqui está um checklist completo de configuração para um novo projeto JavaScript ou TypeScript:

1. Instale as dependências:

   npm install --save-dev prettier eslint eslint-config-prettier husky lint-staged
   

2. Crie o .prettierrc com as preferências da sua equipe

3. Crie o .editorconfig para a base entre editores

4. Configure o ESLint apenas com regras de qualidade de código (sem regras de formatação)

5. Configure Husky + lint-staged para aplicação no pre-commit

6. Adicione scripts npm:

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

7. Execute a formatação inicial em toda a base de código: npm run format

8. Faça commit do código formatado como um único commit para facilitar ignorá-lo no git blame com --ignore-rev

Formatação na Prática

Uma vez que seu pipeline de formatação está configurado, a experiência do dia a dia muda drasticamente:

• Escreva código como quiser. O Prettier reformata ao salvar ou no commit.
• Pull requests mostram apenas mudanças de lógica. Sem mais ruído de espaçamento.
• Novos membros da equipe são produtivos imediatamente. As ferramentas impõem padrões sem necessidade de um documento de guia de estilo.
• Discussões sobre estilo desaparecem. O Prettier é a autoridade, não um desenvolvedor individual.

Quando precisar verificar a estrutura de dados JSON com os quais está trabalhando, nosso JSON Formatter facilita a inspeção — cole qualquer JSON e obtenha formatação legível instantaneamente no seu navegador.

Recursos Relacionados

Para saber mais sobre formatação de código e ferramentas para desenvolvedores:

• Code Minification Guide — Aprenda quando e como minificar JavaScript para produção
• Naming Conventions in Programming — Nomenclatura consistente é a outra metade de código legível
• SQL Formatting Best Practices — Aplique a mesma disciplina de formatação às suas consultas de banco de dados

Formatação consistente é um daqueles raros investimentos de engenharia que dá retorno imediato e continua valendo a pena. Configure uma vez, automatize e gaste sua energia no código que realmente importa.