Biome no Node.js

O Biome no Node.js reúne formatter, linter e organização de imports em uma única ferramenta. Ele pode substituir parte do fluxo baseado em ESLint e Prettier, oferecendo execução rápida, configuração centralizada e binários nativos para diferentes plataformas.

Biome não substitui typecheck, testes ou análise especializada de segurança. Ele encontra problemas sintáticos e padrões suportados pelo próprio linter, enquanto o TypeScript continua responsável pelos tipos. Uma migração segura deve comparar resultados, manter regras essenciais e evitar reformatação junto com mudanças funcionais.

Neste guia, você aprenderá a instalar Biome, configurar biome.json, formatar e lintar JavaScript e TypeScript, organizar imports, integrar com editor, Git hooks e CI, além de migrar gradualmente de ESLint e Prettier.

Instalação

A documentação oficial de Getting Started do Biome recomenda instalar como dependência de desenvolvimento e fixar a versão:

npm install --save-dev --save-exact @biomejs/biome

O --save-exact evita mudanças inesperadas de formatação entre instalações.

Inicialização

npx @biomejs/biome init

O comando cria biome.json. Uma configuração inicial:

{
  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
  "files": {
    "includes": ["src/**", "test/**", "scripts/**"]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

Use o schema compatível com a versão instalada, não copie números antigos sem verificar.

Formatando arquivos

npx biome format --write .

Para apenas verificar:

npx biome format .

O formatter cobre JavaScript, TypeScript, JSON, CSS e outras linguagens suportadas pela versão.

Lint

npx biome lint .

Aplicando correções seguras:

npx biome lint --write .

Correções marcadas como inseguras exigem uma opção explícita e revisão. Não aplique automaticamente em todo o repositório sem avaliar o diff.

Comando check

npx biome check .

check combina formatter, linter e ações de código. Para aplicar:

npx biome check --write .

Scripts do package.json

{
  "scripts": {
    "lint": "biome lint .",
    "lint:fix": "biome lint --write .",
    "format": "biome format --write .",
    "format:check": "biome format .",
    "check": "biome check .",
    "check:fix": "biome check --write .",
    "typecheck": "tsc --noEmit"
  }
}

Veja npm Scripts no Node.js.

Biome não faz typecheck

Este código pode passar pela transformação e ainda conter erro de tipo:

const total: number = 'dez';

Mantenha:

npm run typecheck

Em CI, execute Biome, TypeScript e testes separadamente.

Regras recomendadas

{
  "linter": {
    "rules": {
      "recommended": true
    }
  }
}

Comece com o preset recomendado e habilite regras adicionais quando elas resolvem problemas reais.

Personalizando regras

{
  "linter": {
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "warn"
      },
      "complexity": {
        "noForEach": "off"
      },
      "style": {
        "useConst": "error"
      }
    }
  }
}

Evite centenas de warnings permanentes. Resolva, desabilite com justificativa ou transforme em erro.

Overrides

{
  "overrides": [
    {
      "includes": ["test/**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": {
            "noConsole": "off"
          }
        }
      }
    },
    {
      "includes": ["scripts/**/*.ts"],
      "formatter": {
        "lineWidth": 120
      }
    }
  ]
}

Use overrides pequenos para testes, scripts e arquivos gerados.

Arquivos ignorados

{
  "files": {
    "includes": [
      "**",
      "!dist/**",
      "!coverage/**",
      "!generated/**",
      "!node_modules/**"
    ]
  }
}

Não processe builds, coverage ou código de terceiros.

Organização de imports

Biome pode organizar imports:

npx biome check --write src

A ação remove imports não usados e agrupa caminhos conforme a configuração. Revise side effects:

import './register-instrumentation.js';

Imports executados por efeito colateral não devem ser removidos.

Formatter

Opções comuns:

{
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "always",
      "trailingCommas": "all"
    }
  }
}

Mantenha poucas preferências para aproveitar a formatação automática.

Integração com VS Code

Instale a extensão oficial e configure:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

Compartilhe apenas configurações úteis para toda a equipe.

Biome Language Server

A extensão usa o servidor de linguagem para diagnósticos, formatação e ações. Garanta que ela utilize a versão local do projeto, evitando diferenças entre editor e CI.

Git hooks

Com lint-staged:

{
  "lint-staged": {
    "*.{js,mjs,cjs,ts,mts,cts,json,css}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

Hooks oferecem feedback rápido, mas podem ser ignorados. A CI continua obrigatória.

CI

Biome possui um comando otimizado para pipelines:

npx biome ci .

No GitHub Actions:

- run: npm ci
- run: npx biome ci .
- run: npm run typecheck
- run: npm test
- run: npm run build

Consulte CI para Node.js com GitHub Actions.

Reporters

Escolha output compatível com terminal ou CI. Relatórios JSON podem alimentar ferramentas, mas não inclua caminhos sensíveis em artifacts públicos.

Migrando do Prettier

Um fluxo seguro:

1. fixe a versão do Biome;
2. crie a configuração;
3. compare arquivos representativos;
4. execute em branch dedicada;
5. faça um commit apenas de formatação;
6. ative biome ci;
7. remova Prettier e plugins não usados.

Veja Prettier no Node.js.

Migrando do ESLint

Biome possui uma ferramenta de migração e regras equivalentes para muitos casos, mas não para todo plugin.

1. liste regras críticas;
2. identifique plugins de framework;
3. execute a migração;
4. compare diagnósticos;
5. mantenha ESLint apenas para regras ausentes;
6. remova gradualmente.

Consulte ESLint Flat Config no Node.js.

Uso híbrido

Um projeto pode usar Biome para formatter e regras gerais, mantendo ESLint para plugins específicos:

{
  "scripts": {
    "lint": "biome lint . && eslint .",
    "format": "biome format --write ."
  }
}

Garanta que regras estilísticas do ESLint não conflitem com Biome.

Monorepos

Mantenha biome.json na raiz quando a política é compartilhada. Overrides podem diferenciar apps e packages.

Com Turborepo:

"lint": {
  "outputs": []
}

Com Nx, registre o target ou plugin para aproveitar cache. Veja Turborepo no Node.js e Nx no Node.js.

Arquivos grandes

Se houver lentidão, investigue:

• diretórios gerados;
• minificados;
• snapshots enormes;
• globs amplos;
• arquivos sem suporte;
• execuções duplicadas no editor.

Supressões

Uma supressão deve explicar a exceção:

// biome-ignore lint/suspicious/noExplicitAny: biblioteca externa não fornece tipos
declare const plugin: any;

Evite desabilitar a regra para o arquivo inteiro quando apenas uma linha precisa da exceção.

Safe e unsafe fixes

Correções seguras preservam semântica esperada. Correções inseguras podem alterar comportamento. Execute unsafe fixes apenas em branch, revise o diff e rode testes.

Versão fixada

Biome segue uma política de versionamento em que mudanças de regras e formatação podem ocorrer. Use versão exata e atualize em pull request dedicado.

Binário standalone

Biome também pode ser executado sem Node.js, mas em projetos npm a dependência local simplifica distribuição e lockfile. Evite downloads não verificados no CI.

Segurança

• Fixe a versão.
• Use lockfile.
• Revise correções inseguras.
• Não formate arquivos secretos.
• Proteja reports.
• Atualize em branch dedicada.
• Mantenha typecheck e testes.

Erros comuns

• Substituir typecheck: erros TypeScript passam.
• Migração junto com feature: revisão fica impossível.
• Remover ESLint cedo: regras de plugins desaparecem.
• Versão não fixada: formato muda.
• Processar dist: trabalho duplicado.
• Unsafe fixes automáticos: comportamento muda.
• Editor usa outra versão: CI diverge.
• Hooks sem CI: proteção pode ser pulada.

Configuração recomendada

{
  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
  "files": {
    "includes": [
      "src/**",
      "test/**",
      "scripts/**",
      "*.json"
    ]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

Conclusão

O Biome no Node.js reduz a quantidade de ferramentas ao combinar formatter, linter e organização de imports. Instalação com versão exata e um único arquivo de configuração tornam o fluxo rápido e previsível.

Migre de forma gradual, mantenha typecheck e testes e preserve ESLint quando plugins específicos ainda são necessários. Com editor e CI usando a mesma versão, Biome melhora consistência sem esconder problemas de comportamento.