RFC: Changing `experimentalSortImports.groups` default order #18688

leaysgur · 2026-01-29T05:26:06Z

leaysgur
Jan 29, 2026
Collaborator

Oxfmt experimentally implements a feature to order import declarations.

The default grouping order currently looks like this:

[
  "type-import",
  ["value-builtin", "value-external"],
  "type-internal",
  "value-internal",
  ["type-parent", "type-sibling", "type-index"],
  ["value-parent", "value-sibling", "value-index"],
  "unknown",
]

📝 Code example

import type { SubpathType } from "#types"; // [type, subpath, external, import] [type, named]
import type { Readable } from "node:stream"; // [type, builtin, import] [type, named]
import type { FC } from "react"; // [type, external, import] [type, named]

import { subpathFn } from "#lib"; // [subpath, external, import] [value, named]
import fs from "node:fs"; // [builtin, import] [value, default]
import React from "react"; // [external, import] [value, default]
import { z } from "zod"; // [external, import] [value, named]

import type { AppConfig } from "~/types"; // [type, internal, import] [type, named]

import { config } from "~/config"; // [internal, import] [value, named]

import type { ParentType } from "../types"; // [type, parent, import] [type, named]
import type { IndexType } from "./index.ts"; // [type, index, import] [type, named]
import type { SiblingType } from "./types"; // [type, sibling, import] [type, named]

import { parentFn } from "../lib"; // [parent, import] [value, named]
import { indexFn } from "./index"; // [index, import] [value, named]
import { siblingFn } from "./lib"; // [sibling, import] [value, named]
import styles from "./local.module.css"; // [style, sibling, import] [value, default]

import "reflect-metadata"; // [side-effect, external, import] [side-effect, value]
import "~/polyfill"; // [side-effect, internal, import] [side-effect, value]
import "../globals/polyfill"; // [side-effect, parent, import] [side-effect, value]
import "normalize.css"; // [side-effect-style, side-effect, style, external, import] [side-effect, value]
import "./component.css"; // [side-effect-style, side-effect, style, sibling, import] [side-effect, value]

This is (roughly) equivalent to the default behavior of the reference implementation, eslint-plugin-perfectionist/sort-imports.

Generally, from far to near
But type takes precedence
Does not distinguish side-effect

However, after examining sort-imports configurations on GitHub (like `prettier-plugin-sort-imports, etc), We wondered if Oxfmt could provide better defaults.

⚠️ Blank lines between groups are out of scope for this discussion. Also, please remember that this is just the defaults and can be freely changed by your config.

leaysgur · 2026-01-29T05:26:36Z

leaysgur
Jan 29, 2026
Collaborator Author

Our top candidate:

[
  "builtin",
  ["external", "subpath"],
  "internal",
  ["parent", "sibling", "index"],
  "style",
  "side-effect",
  "side-effect-style",
  "unknown"
]

📝 Code example

import fs from "node:fs"; // [builtin, import] [value, default]
import type { Readable } from "node:stream"; // [type, builtin, import] [type, named]

import { subpathFn } from "#lib"; // [subpath, external, import] [value, named]
import type { SubpathType } from "#types"; // [type, subpath, external, import] [type, named]
import React from "react"; // [external, import] [value, default]
import type { FC } from "react"; // [type, external, import] [type, named]
import { z } from "zod"; // [external, import] [value, named]

import { config } from "~/config"; // [internal, import] [value, named]
import type { AppConfig } from "~/types"; // [type, internal, import] [type, named]

import { parentFn } from "../lib"; // [parent, import] [value, named]
import type { ParentType } from "../types"; // [type, parent, import] [type, named]
import { indexFn } from "./index"; // [index, import] [value, named]
import type { IndexType } from "./index.ts"; // [type, index, import] [type, named]
import { siblingFn } from "./lib"; // [sibling, import] [value, named]
import type { SiblingType } from "./types"; // [type, sibling, import] [type, named]

import styles from "./local.module.css"; // [style, sibling, import] [value, default]

import "reflect-metadata"; // [side-effect, external, import] [side-effect, value]
import "~/polyfill"; // [side-effect, internal, import] [side-effect, value]
import "../globals/polyfill"; // [side-effect, parent, import] [side-effect, value]

import "normalize.css"; // [side-effect-style, side-effect, style, external, import] [side-effect, value]
import "./component.css"; // [side-effect-style, side-effect, style, sibling, import] [side-effect, value]

Generally, from far to near
(value + type) > style > side-effect
- side-effect goes last

1 reply

cpojer Jan 29, 2026
Collaborator

I'm in favor of this style. I don't usually look at my imports, but I do care about minimizing "diffs" when imports change. For example, when I remove a type keyword, I'd like that import to stay in the same position. This new default looks like it reduces the amount of diff lines when imports change.

One thing that I am still curious about is why side-effects go last in most configurations. Side effects always have to run to set up an application, but if they are at the bottom they are run after the entire application's code (up until async import boundaries) is evaluated. If we move side-effects to the top they could technically set up various things faster. I'm not sure without real world benchmarking if this hypothesis is true, but it is possible. I don't feel too strongly about it, though.

leaysgur · 2026-01-29T05:27:04Z

leaysgur
Jan 29, 2026
Collaborator Author

[
  "builtin",
  ["external", "subpath"],
  "internal",
  ["parent", "sibling", "index"],
  "type-builtin",
  ["type-external", "type-subpath"],
  "type-internal",
  "type-parent", "type-sibling", "type-index",
  "style",
  "side-effect",
  "side-effect-style",
  "unknown",
]

📝 Code example

import fs from "node:fs"; // [builtin, import] [value, default]

import { subpathFn } from "#lib"; // [subpath, external, import] [value, named]
import React from "react"; // [external, import] [value, default]
import { z } from "zod"; // [external, import] [value, named]

import { config } from "~/config"; // [internal, import] [value, named]

import { parentFn } from "../lib"; // [parent, import] [value, named]
import { indexFn } from "./index"; // [index, import] [value, named]
import { siblingFn } from "./lib"; // [sibling, import] [value, named]

import type { Readable } from "node:stream"; // [type, builtin, import] [type, named]

import type { SubpathType } from "#types"; // [type, subpath, external, import] [type, named]
import type { FC } from "react"; // [type, external, import] [type, named]

import type { AppConfig } from "~/types"; // [type, internal, import] [type, named]

import type { ParentType } from "../types"; // [type, parent, import] [type, named]

import type { SiblingType } from "./types"; // [type, sibling, import] [type, named]

import type { IndexType } from "./index.ts"; // [type, index, import] [type, named]

import styles from "./local.module.css"; // [style, sibling, import] [value, default]

import "reflect-metadata"; // [side-effect, external, import] [side-effect, value]
import "~/polyfill"; // [side-effect, internal, import] [side-effect, value]
import "../globals/polyfill"; // [side-effect, parent, import] [side-effect, value]

import "normalize.css"; // [side-effect-style, side-effect, style, external, import] [side-effect, value]
import "./component.css"; // [side-effect-style, side-effect, style, sibling, import] [side-effect, value]

Generally, from far to near
value > type > style > side-effect
- Explicitly type after value

0 replies

TiBianMod · 2026-01-29T13:26:12Z

TiBianMod
Jan 29, 2026

i will like my import type to be in the buttom of all imports

something like this

import { Cookie } from "#http/request/cookie.js";
import { get, omit, pick, sortBy } from "lodash";
import { ValidationException } from "#validation/exceptions.js";
import mimeDB from "mime-db";
import type { Application } from "#server/application.js";
import type { BodyParserStore } from "#http/request/body_parser/body_parser_store.js";
import type { Encryption } from "#encryption/encryption.js";
import type { HeaderByQuality, HttpMethodType } from "#http/request/types.js";
import type { RouteNodeState } from "#router/types.js";
import type { ZodObject, ZodRawShape } from "#validation/types.js";

please support this option!!

0 replies

NMinhNguyen · 2026-01-29T18:51:28Z

NMinhNguyen
Jan 29, 2026

I’m curious why #foo imports are considered external - aren’t they typically internal? https://nodejs.org/api/packages.html#subpath-patterns

{
  "imports": {
    "#internal/*.js": "./src/internal/*.js"
  }
}

1 reply

U3erKa Feb 8, 2026

I think it makes sense to treat them same as import aliases (e.g. "@/*", "~/*").

For example this imports can be used instead of (or in addition to) paths from tsconfig.json for Node.js scripts, e.g.:

{
  "imports": {
    "##/*": "./*.ts",
    "##/assets/*": "./assets/*",
    "##/*.js": "./*.tsx"
  }
}

rafaell-lycan · 2026-01-30T12:58:04Z

rafaell-lycan
Jan 30, 2026

Right now I'm using @ianvs/prettier-plugin-sort-imports (fork from @trivago/prettier-plugin-sort-imports) with Prettier, and would be awesome to have a similar API and good defaults.

Here is an example of what we've been using:

[
  "<BUILTIN_MODULES>",
  "<THIRD_PARTY_MODULES>",
  "",
  "^(?!.*[.]css$)[./].*$",
  "",
  ".css$"
]

0 replies

leaysgur · 2026-02-16T08:41:03Z

leaysgur
Feb 16, 2026
Collaborator Author

Thank you all very much. 🙏🏻

#19427

0 replies

This comment has been hidden.

Sign in to view

This comment has been hidden.

Sign in to view

This comment has been hidden.

Sign in to view

Uh oh!

RFC: Changing experimentalSortImports.groups default order #18688

Uh oh!

Uh oh!

leaysgur Jan 29, 2026 Collaborator

Replies: 7 comments · 3 replies

Uh oh!

Uh oh!

leaysgur Jan 29, 2026 Collaborator Author

Uh oh!

cpojer Jan 29, 2026 Collaborator

Uh oh!

Uh oh!

leaysgur Jan 29, 2026 Collaborator Author

Uh oh!

TiBianMod Jan 29, 2026

Uh oh!

NMinhNguyen Jan 29, 2026

Uh oh!

Uh oh!

U3erKa Feb 8, 2026

Uh oh!

rafaell-lycan Jan 30, 2026

This comment has been hidden.

This comment has been hidden.

Uh oh!

leaysgur Feb 16, 2026 Collaborator Author

RFC: Changing `experimentalSortImports.groups` default order #18688

leaysgur
Jan 29, 2026
Collaborator

Replies: 7 comments 3 replies

leaysgur
Jan 29, 2026
Collaborator Author

cpojer Jan 29, 2026
Collaborator

leaysgur
Jan 29, 2026
Collaborator Author

TiBianMod
Jan 29, 2026

NMinhNguyen
Jan 29, 2026

rafaell-lycan
Jan 30, 2026

leaysgur
Feb 16, 2026
Collaborator Author