Ordenação de importações

Biome permite ordenar declarações de importação usando a ordenação natural

Esse recurso é habilitado por padrão, mas pode ser desabilitado através de configuração:

biome.json

{
  "organizeImports": {
    "enabled": false
  }
}

Como as importações são ordenadas

As declarações de importação são classificadas por distância. Os módulos que são “distantes” do usuário são colocados na parte superior, e módulos que são “próximos” ao usuário são colocados na parte inferior:

1. módulos que são importados via protocolo bun:. Isso é aplicável quando o código é executado usando Bun;
2. módulos integrados do Node.js que são importados explicitamente via protocolo node: e módulos integrados comuns do Node.js, como assert;
3. módulos importados via protocolo npm:. Isso é aplicável quando o código é executado usando Deno;
4. módulos importados via URL;
5. módulos importados de bibliotecas;
6. módulos importados através de importações absolutas;
7. módulos importados de um nome prefixado por #. Isso é aplicável quando é usado o recurso Importações de Subcaminho do Node.js;
8. módulos importados através de importações relativas;
9. módulos que não puderam ser identificados pelos critérios anteriores;

Por exemplo, dado o seguinte código:

example.ts

import uncle from "../uncle";
import sibling from "./sibling";
import express from "npm:express";
import imageUrl from "url:./image.png";
import assert from "node:assert";
import aunt from "../aunt";
import { VERSION } from "https://deno.land/std/version.ts";
import { mock, test } from "node:test";
import { expect } from "bun:test";
import { internal } from "#internal";
import { secret } from "/absolute/path";
import React from "react";

As importações serão ordenadas dessa forma:

example.ts

 import { expect } from "bun:test";
 import assert from "node:assert";
 import { mock, test } from "node:test";
 import express from "npm:express";
 import { VERSION } from "https://deno.land/std/version.ts";
 import React from "react";
 import { secret } from "/absolute/path";
 import { internal } from "#internal";
 import aunt from "../aunt";
 import uncle from "../uncle";
 import sibling from "./sibling";
 import imageUrl from "url:./image.png";

Você pode aplicar a ordenação de duas formas: através do CLI ou pela extensão do VSCode.

Importações agrupadas

É muito comum ter declarações de importações em uma certa ordem, principalmente quando você trabalha em um projeto frontend, e você importa arquivos CSS:

example.js

import "../styles/reset.css";
import "../styles/layout.css";
import { Grid } from "../components/Grid.jsx";

Outro caso comum é importar arquivos de polyfill ou shim, que precisam estar ao topo do arquivo:

example.js

import "../polyfills/array/flatMap";
import { functionThatUsesFlatMap } from "./utils.js";

Nesses casos, o Biome irá ordenar todos esses três tipos de importações, e pode acontecer que a ordem possa quebrar sua aplicação.

Para evitar isso, crie um “grupo” de importações. Você pode criar um “grupo” adicionando uma nova linha para separar os grupos.

Ao fazer isso, o Biome irá limitar a ordenação somente as declarações de importações que pertencem ao mesmo grupo:

example.js

// grupo 1, apenas este dois arquivos serão ordenados
import "../styles/reset.css";
import "../styles/layout.css";

// grupo 2, apenas este será ordenado
import { Grid } from "../components/Grid.jsx";

example.js

// grupo 1, o polyfill/shim
import "../polyfills/array/flatMap";

// grupo 2, os arquivos que precisam do polyfill/shim
import { functionThatUsesFlatMap } from "./utils.js";

Ordenando importações através do CLI

Usando o comando check, com a opção --write.

biome check --write ./path/to/src

Ordenando importações através da extensão do VSCode

A extensão do VSCode do Biome suporta a ordenação de importações através da ação de código (code action) “Organize Imports”. Por padrão, essa ação será executada ao usar o atalho de teclado ⇧+Alt+O, ou é acessível via Paleta de Comandos (Command Palette) (Ctrl/⌘+⇧+P) ao selecionar Organizar as Importações (Organize Imports).

Você pode adicionar o seguinte à configuração do seu editor se você deseja que a ação seja executada automaticamente ao salvar em vez de chamá-la manualmente:

settings.json

{
  "editor.codeActionsOnSave":{
    "source.organizeImports.biome": "explicit"
  }
}