Specify import groups and automatic add blank lines between them

[ceopaludetto]

eslint-plugin-import has a nice feature to automatic add blank lines between import groups, I also miss the ability to define custom import groups, something like this:

// biome.json
{
  "organizeImports": {
    "enabled": true,
    
    "addBlankLinesBetweenImports": true,
    "importGroups": [
      "types",
      "bun",
      "node",
      "module",
      ["siblings", "parents"]
    ]
  },
}

This will resolve to:

import type { ReactNode } from "react"
import type { AnotherType } from "./another"

import { ... } from "bun:sql"

import { readFile } from "node:fs"

import { forwardRef } from "react"

import { anotherFn } from "./another"
import { somethingFn } from "../something"

Groups specified in arrays will be combined together:

[
  "module",
  ["bun", "node"]
]

import {} from "react"

import {} from "bun:sql"
import {} from "node:fs"

addBlankLinesBetweenImports take a boolean and is false by default
importGroups take a boolean or an array and is true by default, which will follow the default order specified in docs:

---

Related eslint links:

• https://github.com/import-js/eslint-plugin-import/blob/HEAD/docs/rules/order.md#newlines-between-ignorealwaysalways-and-inside-groupsnever
• https://github.com/import-js/eslint-plugin-import/blob/HEAD/docs/rules/order.md#groups-array

[ematipico]

I am not sure about the safety of this option. I don't know anything about the plugin you mentioned, so I will speak about Biome.

Hard lines in our import sorting are vital for users to move side effects modules where the user needs: https://biomejs.dev/analyzer/#grouped-imports

If we decided on an option like the one you mentioned, we wouldn't be able to support this behaviour, or we would risk adding too many options, making it too complex.

What do you think? As I said, I don't know the plugin, so I might have missed something

[ceopaludetto]

The eslint plugin actually ignores side effect imports and leave the import "as is" since the order matters, as you mentioned. Some examples:

• If you use newlines-between: always, and the side effect import is between two groups, the side effect import will stick to the immediately next group, but the order will be preserved, so:

import { forwardRef } from "react"
import "./styles.css"
import { another } from "./another"

// formats to

import { forwardRef } from "react"

import "./styles.css"
import { another } from "./another"

If the side effect import is located between two imports of the same group, it keeps the same position:

import { forwardRef } from "react"
import { another } from "./another"
import "./styles.css"
import { something } from "./something"

// formats to

import { forwardRef } from "react"

import { another } from "./another"
import "./styles.css"
import { something } from "./something"

I agree with you about the safety of this enforcement, some scenarios may cause incorrect formatting. But also, a lot of projects doesn't have/need side effect imports, so a option to reorganize groups in a deterministic way will be enjoyable. Maybe the addBlankLinesBetweenImports options is sufficient, we can keep hard lines behavior by default and allow users to toggle the default behavior, what you think?

[shellscape]

that sounds like a great compromise

[ematipico]

We could start by implementing the option suggested: addBlankLinesBetweenImports

I propose different names, though: separtedGroups, blankLineBetweenGroups, or something else... I think it's misleading is the "import" in the name, because the option doesn't add lines between imports but between grouped imports.

By default, it should be false. If anyone wants to give it a try, feel free to open an issue :)

[MarkLyck]

I like blankLineBetweenImportGroups! Would love to see this feature added to biomeJS. Right now I'm relying on a prettier plugin to handle this.

[KurtGokhan]

I would like to see this feature too. As far as I understand, Biome adapts a formating similar to VSCode. But eslint-plugin-import has the most comprehensive import ordering with its import/order rule.

It has a name for import groups and basically you can mix groups together via configuration or put space between them. We set it in a way that there are spaces between "external", "absolute", "relative" and "type-only" imports. The resulting code is often more readable.

Maybe that many configuration options is against Biome's philosophy. I think a general opinionated configuration that is balanced and works for most projects can be found.

[rubiesonthesky]

Another way to sort imports is to use Prettier plugin https://github.com/trivago/prettier-plugin-sort-imports . But since we moved from Prettier to Biome for formatting, it's no longer possible to use that. :(

I think it would be fine not to have too many options about this, but I'd like to be able to follow the convention from that plugin (or eslint-plugin-import).

Well, the settings that I'd like to be able to use with biome are these from the prettier plugin. This resulted same order as what Typescript's Organize imports was doing before version 5. Which means, that there will be at least 2 groups: one group for "external imports" and one group for "local imports". And there is empty line between them for separation.

  "importOrder": ["^[./]"],
  "importOrderSeparation": true,
  "importOrderSortSpecifiers": true,
  "importOrderParserPlugins" : ["typescript", "classProperties", "decorators-legacy"],
  "importOrderCaseInsensitive": true,

I think there are a lot motivation for this kind of grouping. One big motivation for me, is to able to easily scan what that file is using from external imports. And if you have accidentally imported something from external package, when you meant to import symbol from local project.

[sethstha]

I am using an alternative way to fix this. If you are using VSCode you can add this to your settings.json

"editor.codeActionsOnSave": {
  "source.organizeImports": "always"
}

Also, if you want to use your own order you can use extensions like https://marketplace.visualstudio.com/items?itemName=alfnielsen.vsc-organize-imports

[ChiefORZ]

of course there is alternatives, but it would be awesome to have an all-in-one tool that can even be checked on the CI. For that reason it would be awesome to have this option in biome

[marko-hologram]

Your solution implies everyone must use VSCode. It's better to have an editor agnostic way of dealing with this so that people can use any editor they prefer and not be forced into using VSCode. Also as mentioned, being able to run this in CI as well.

I personally use VSCode, but many people don't.

[kaumac]

Would also love this feature. I'm considering migrating to Biome from Prettier where I use the prettier plugin from Trivago like @rubiesonthesky .

From all import sorting tools I've tried, it seems to be the most flexible and reliable.

[Netail]

Regarding the custom import order; we currently also make use of Trivago's prettier sort imports plugin, which uses an array of regular expressions to customize the import order. The plugin has 739,534+ weekly downloads, which does suggests it's a wanted features by the community.

[matsko]

I also make use of the Trivago plugin for Pretterier across various projects. It helps to simplify commit diff comparisons since imports end in the same order unless new imports are introduced in a change. Excellent feature to have.

[pijusz]

Seems like Biome organizeImports is quite stable right now. Also adding other library that is popular for sorting imports:
@ianvs/prettier-plugin-sort-imports
Example config:

  "importOrder": [
    "<TYPES>",
    "",
    "^react",
    "<THIRD_PARTY_MODULES>",
    "",
    "^~/layouts(.*)$",
    "^~/components(.*)$",
    "",
    "^~/hooks(.*)$",
    "^~/lib(.*)$",
    "",
    "^~/assets(.*)$",
    "^~/styles(.*)$",
    "",
    "^[./]"
  ],

[ThenTech]

I'm currently also using this plugin with my own importOrder, which also correctly separates internal absolute imports as @eMerzh mentions below. This is the main thing blocking us to replace prettier with biome. Since prettier takes 9 seconds to run vs only .7s for biome, the change would be very welcome.

[pijusz]

When I started using ordering plugins, this one seems most flexible. Only issue with that plugin currently is, it doesn't sort unnamed imports properly:
import "~/styles/...";

Just by supporting regex'es it should work really well. Nice addition would be type and general third party selection.

[FranciscoKloganB]

I haven't set up Biome myself (yet) but I am about to. I've decided to drop prettier altogether in favor of Biome. If you are only using prettier for sorting at this point, maybe you can use eslint-config-biome instead, this allows you to use eslint and biome.

The downside of this approach is that you will lose some of the performance benefits that Biome gives, especially in large repositories and eventually mono repositories. This is even more true if the rule you want from eslint is an import-sorter. However, my idea is to let biome do the heavy lifting/format across all the code and then do a second eslint pass with a minimal set of rules targetting specific files.

The advantage here is that, as biome becomes better you can drop some eslint plugins. For my case, this approach is, unfortunately necessary, because I use a bunch of eslint plugins that Biome does not have support for, and, probably won't ever. To name a few: eslint-plugin-xstate, @tanstack/eslint-plugin-query, @pandacss/eslint-plugin, eslint-plugin-react-hook-form, eslint-plugin-sort-exports, eslint-plugin-storybook, eslint-plugin-testing-library and eslint-plugin-vitest. 😓

Fortunately, for most of these plugins, I can target specific folders and or files which saves me some seconds. E.g., only run eslint-plugin-xstate within files that have .machine.ts extension, storybook only for stories.tsx, and so on. :)

[scallaway]

However, my idea is to let biome do the heavy lifting/format across all the code and then do a second eslint pass with a minimal set of rules targetting specific files.

I very much like this idea.

I'm currently in the process of investigating whether we can swap over fully to biome from eslint and prettier and I think we can probably get about 90% of the way there.

However, import ordering is a big blocker for us since we're creating files and importing files very frequently. We also make use of @tanstack/eslint-plugin-query which, as you say, will probably never be supported by biome.

I wonder if you can go a step further and only run eslint as a pre-commit hook or similar, so that 99% of the time you're only running biome. Especially if you're only using eslint for things that don't change that often!

[eMerzh]

One thing that is missing atm is support for custom path like

import theme, { prop } from 'components/theme'
import styled, { css, ThemeProvider } from 'styled-components'

theme is in fact an "absolute" internal import, and should thus be found after the style-component node_module import 🤔

[ChiefORZ]

this is the ticket with top activity, but still not getting any attention from the authors - why? 😔

[ematipico]

There are a couple of reasons:

• The most important one is that we didn't want to move forward until we fixed an issue around "side effect" modules. We felt that fixing bugs was way more important than adding new features
• The second one, is that different users come from various backgrounds, different DX due to various plugins in the ecosystem, an different expectations. Meeting all these expectations is more challenging than it sounds.

Lead Maintainer @Conaclos has been thinking about this for a long time and has been writing an RFC for all of us. However, writing an RFC is a difficult task. Considering all the previous assessments, it is time-consuming, which puts pressure on him. I decided to cut him some slack and focus on other things for the time being. Once he has some fresh energy and less pressure, we will eventually see a fantastic RFC with many goodies.

So, unless someone wants to step up and concretely help - funding the project so we can allocate a full-time person on the project or help us with the developments - I kindly ask you to refrain from writing such messages, because they don't bring any value to the community. We do things on our own time and priority with the resources we have.

[e965]

@ematipico Can you create an issue on Polar so that people have the opportunity to fund the implementation of this feature?

[ematipico]

We have frozen the funding via Polar until we have a clear policy in our Governance. This is really important to us because we want to set clear expectations about how money is funnelled, for you users that care about the project, our sponsors and the Biome team.

#2693

[ematipico]

Closing. Please jump in #3015 where a great RFC awaits you