Pular para o conteúdo

Usando o Biome em projetos grandes

O Biome pode fornecer algumas ferramentas que podem ajudá-lo a usá-lo corretamente em projetos grandes, como monorepos ou workspaces que contêm múltiplos projetos.

Quando você usa os recursos do Biome - seja com a CLI ou o LSP - a ferramenta procura pelo arquivo de configuração mais próximo usando o diretório de trabalho atual.

Se o Biome não encontrar o arquivo de configuração lá, ele começa a percorrer para cima os diretórios do sistema de arquivos, até encontrar um.

Você pode aproveitar esse recurso para aplicar diferentes configurações com base no projeto/pasta.

Vamos supor que temos um projeto que contém uma aplicação de backend e uma aplicação de frontend.

  • Directoryapp
    • Directorybackend
      • biome.json
      • package.json
    • Directoryfrontend
      • biome.json
      • Directorylegacy-app
        • package.json
      • Directorynew-app
        • package.json

Isso significa que quando você executa o Biome dentro de app/backend, o Biome usará o arquivo de configuração app/backend/biome.json. E quando você executa de app/frontend/legacy-app ou app/frontend/new-app, o Biome usará o arquivo de configuração app/frontend/biome.json.

Monorepos são repositórios particulares onde múltiplos pacotes são armazenados e mantidos em um grande repositório. Cada pacote pode conter sua própria configuração.

Desde a v2, o Biome suporta monorepos nativamente, e você precisará configurar o projeto da seguinte maneira.

  1. Crie um arquivo biome.json na raiz do monorepo. Usaremos as regras recomendadas e personalizaremos as opções do formatador:

    biome.json
    {
    "linter": {
    "enabled": true,
    "rules": {
    "recommended": true
    }
    },
    "formatter": {
    "lineWidth": 120,
    "indentStyle": "space",
    "indentWidth": 6
    }
    }

    Este arquivo é chamado de configuração raiz e define as opções base dentro do projeto. No entanto, configurações aninhadas podem decidir aderir a essas opções ou não. Vamos ver como.

  2. Crie arquivos de configuração aninhados, um em cada pacote onde for necessário. Esses arquivos de configuração aninhados devem ter o campo "root" definido como false. Além disso, queremos que esses pacotes sigam os padrões de formatação definidos na configuração raiz. Para isso, usaremos uma nova microssintaxe disponível no Biome v2, que é "extends": "//". Essa sintaxe diz ao Biome para estender da configuração raiz, independentemente de onde a configuração aninhada esteja.

    Vamos criar dois arquivos de configuração, um dentro de packages/logger e outro dentro de packages/generate. No primeiro, desativaremos noConsole, e em packages/generate desativaremos o formatador porque esses são arquivos gerados por código:

    packages/logger/biome.json
    {
    "root": false,
    "extends": "//",
    "linter": {
    "rules": {
    "suspicious": {
    "noConsole": "off"
    }
    }
    }
    }
    packages/generate/biome.json
    {
    "root": false,
    "extends": "//",
    "formatter": {
    "enabled": false
    }
    }

    Por conveniência, quando você usa a microssintaxe extends: "//", você pode omitir "root": false, porque já está implícito que esta configuração não é uma configuração raiz:

    packages/generate/biome.json
    {
    "root": false,
    "extends": "//",
    "formatter": {
    "enabled": false
    }
  3. Agora, vamos supor que temos um novo pacote em packages/analytics que é mantido por uma equipe diferente. Essa equipe segue padrões de codificação totalmente diferentes, então eles não querem herdar opções da configuração raiz. Para eles, basta omitir "extends": "//" do arquivo de configuração e alterar as opções de formatação:

    packages/analytics/biome.json
    {
    "root": false,
    "formatter": {
    "lineWidth": 100,
    }
    }
  4. Agora que tudo está configurado, você tem algumas opções. Você pode executar os comandos biome da raiz do projeto ou dos pacotes individuais. O Biome respeitará todas as configurações!

Outras maneiras de compartilhar um arquivo de configuração

Section titled “Outras maneiras de compartilhar um arquivo de configuração”

Como vimos acima, o campo extends permite que você divida sua configuração em vários arquivos. Dessa forma, você pode compartilhar configurações comuns entre diferentes projetos ou pastas. A sintaxe "extends": "//" é um atalho conveniente quando você deseja que as configurações aninhadas se estendam da configuração raiz, mas às vezes você pode querer usar uma configuração ainda mais personalizada.

Além de "//", a configuração extends também aceita valores de array. Nesse caso, cada valor no array deve ser um caminho para outra configuração a ser estendida.

Por exemplo, veja como você pode configurar sua configuração para estender um arquivo de configuração common.json:

biome.json
{
"extends": ["./common.json"]
}

As entradas definidas em extends são resolvidas a partir do caminho onde o arquivo biome.json está definido. Elas são processadas na ordem em que são listadas, com as configurações em arquivos posteriores substituindo as anteriores.

Arquivos dos quais você extend não podem extend outros arquivos por sua vez.

Note que os caminhos em um arquivo de configuração são sempre resolvidos a partir da pasta em que o arquivo biome.json/biome.jsonc reside. Ao usar o campo extends, isso significa que os caminhos em uma configuração compartilhada são interpretados a partir da localização da configuração que a está estendendo, e não da pasta do arquivo que está sendo estendido.

Por exemplo, vamos supor um projeto que contém dois diretórios backend/ e frontend/, cada um com seu próprio biome.json que ambos estendem uma configuração common.json na pasta raiz:

  • Directorybackend/
    • Directorysrc/
    • Directorytest/
    • biome.json
  • Directoryfrontend/
    • Directorysrc/
    • Directorytest/
    • biome.json
  • common.json
common.json
{
"files": {
"includes": ["src/**/*.js", "test/**/*.js"],
},
"linter": {
"includes": ["**", "!test"]
}
}
frontend/biome.json
{
"extends": ["../common.json"]
}
  • Ao executar o Biome a partir da pasta frontend/, ele será configurado para formatar e analisar todos os arquivos JavaScript nas pastas frontend/src/ e frontend/test/, e apenas formatar os arquivos na pasta frontend/src/. Isso funciona porque os caminhos especificados em common.json são interpretados a partir da pasta frontend/, pois é onde o arquivo biome.json reside.
  • Supondo que backend/biome.json seja igual a frontend/biome.json, ele terá o mesmo comportamento, exceto que os caminhos serão interpretados a partir da pasta backend/.

Note que nesta configuração, tanto frontend/biome.json quanto backend/biome.json são considerados configurações raiz. Você não poderá executar o Biome da raiz do repositório, a menos que use a opção de CLI --config-path e aponte para uma das configurações.

Exportando uma configuração do Biome de um pacote NPM

Section titled “Exportando uma configuração do Biome de um pacote NPM”

O Biome também é capaz de resolver arquivos de configuração da pasta node_modules/. Assim, você pode exportar seu arquivo de configuração de um pacote e importá-lo em vários projetos.

Para fazer isso, a primeira coisa a fazer é configurar sua configuração “compartilhada” do Biome de uma certa maneira. Vamos supor que você queira compartilhar uma configuração de um pacote chamado @org/shared-configs, usando o especificador @org/shared-configs/biome. Você precisa criar uma entrada exports no package.json deste pacote:

package.json
{
"name": "@org/shared-configs",
"type": "module",
"exports": {
"./biome": "./biome.json"
}
}

Certifique-se de que @org/shared-configs está corretamente instalado em seu projeto e atualize o arquivo biome.json para se parecer com o seguinte trecho:

biome.json
{
"extends": ["@org/shared-configs/biome"]
}

O Biome tentará resolver sua biblioteca @org/shared-configs/ a partir do seu diretório de trabalho. O diretório de trabalho é:

  • ao usar a CLI, a pasta de onde você executa seus scripts. Geralmente, corresponde à localização do seu arquivo package.json;
  • ao usar o LSP, a pasta raiz do seu projeto.

Para mais informações sobre o algoritmo de resolução, consulte a documentação do Node.js.