Ordenación de importaciones

Biome permite clasificar las declaraciones de importación utilizando un orden natural.

Esta función está activada por defecto, pero puede desactivarse mediante la configuración:

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

Cómo se clasifican las importaciones

Las declaraciones de importación se ordenan por “distancia”. Los módulos que están “más lejos” del usuario se colocan en la parte superior, los módulos que están “más cerca” del usuario se colocan en la parte inferior:

módulos importados mediante el protocolo bun:. Esto es aplicable cuando se escribe código ejecutado por Bun;
módulos integrados de Node.js que se importan explícitamente mediante el protocolo node: y módulos integrados comunes de Node, como assert;
módulos importados mediante el protocolo npm:. Esto es aplicable cuando se escribe código ejecutado por;
módulos que contienen el protocolo :. Estos suelen considerarse “módulos virtuales”, módulos que son inyectados por tu entorno de trabajo, e.g. vite;
módulos importados mediante URL;
módulos importados de bibliotecas;
módulos importados mediante importaciones absolutas;
módulos importados de un nombre prefijado por #. Esto es aplicable cuando se utiliza Node’s subpath imports;
módulos importados mediante importaciones relativas;
módulos que no pudieron identificarse con los criterios anteriores;

Por ejemplo, dado el siguiente código:

import uncle from "../uncle";
import sibling from "./sibling";
import express from "npm:express";
import imageUrl from "url:./image.png";
import { sortBy } from "virtual:utils";
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";

Se ordenarán así:

import { expect } from "bun:test";
import assert from "node:assert";
import { mock, test } from "node:test";
import express from "npm:express";
import { sortBy } from "virtual:utils";
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";

Puedes aplicar la clasificación de dos formas: através del CLI o la extension de VSCode.

Importaciones agrupadas

Es muy común tener las declaraciones de importación en un cierto orden, principalmente cuando estas trabajando en un proyecto frontend, e importas archivos CSS:

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

Otro caso común es la importación de archivos polyfills o shim, que necesitan permanecer en el archivo superior:

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

En estos casos, Biome ordenará estas tres importaciones, y puede ocurrir que el orden rompa tu aplicación.

Para evitar esto, crea un “grupo” de importaciones. Creas un “grupo” añadiendo una nueva línea para separar los grupos.

De este modo, Biome limitará la clasificación únicamente a las declaraciones de importación que pertenezcan al mismo grupo:

// grupo 1, sólo se ordenarán estos dos archivos
import "../styles/reset.css";
import "../styles/layout.css";

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

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

// grupo 2, los archivos que requieren el polyfill/shim
import { functionThatUsesFlatMap } from "./utils.js";

Efectos secundarios de importaciones

Los efectos secundarios de importaciones son declaraciones de importacion que normalmente no importan ningún nombre:

import "./global.js";

Dado que es difícil determinar qué efectos secundarios desencadena un módulo, el clasificador de importaciones asume que cada importación de efectos secundarios forma su propio grupo de importaciones.

Por ejemplo, las siguientes importaciones forman 4 grupos de importación.

import sibling from "./sibling"; // Import group 1
import { internal } from "#internal"; // Import group 1
import "z"; // Import group 2
import "a"; // Import group 3
import React from "react"; // Import group 4
import assert from "node:assert"; // Import group 4

Cada grupo se clasifica independientemente de la siguiente manera:

import { internal } from "#internal"; // Import group 1
import sibling from "./sibling"; // Import group 1
import "z"; // Import group 2
import "a"; // Import group 3
import assert from "node:assert"; // Import group 4
import React from "react"; // Import group 4

Ordenando importaciones mediante el CLI

Utilizando el comando check, con la opción --write. Si sólo deseas ordenar las importaciones, puedes utilizar check de la siguiente manera:

biome check \
    --formatter-enabled=false\
    --linter-enabled=false \
    --organize-imports-enabled=true \
    --write \
    ./path/to/src

Ordenando importaciones mediante la extensión de VSCode

La extensión Biome VS Code permite ordenar las importaciones mediante la acción de código (code action) “Organize imports” Por defecto, esta acción puede ejecutarse utilizando el atajo de teclado ⇧+Alt+O, o es accesible a través de la Paleta de Comandos (Command Palette) (Ctrl/⌘+⇧+P) seleccionando Organizar importaciones (Organize Imports).

Puedes añadir lo siguiente a la configuración de tu editor si quieres que la acción se ejecute automáticamente al guardar en lugar de llamarla manualmente:

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