Differences between sortImports and eslint-plugin-perfectionist/sort-imports

[ddanielcruzz]

I was working on migrating from eslint-plugin-perfectionist/sort-imports to oxfmt’s sortImports, and ran into several discrepancies that made the process more difficult than expected.

The documentation states:

Based on [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports)

However, there are a number of differences that are not immediately obvious:

1. Custom groups

   • oxfmt uses glob patterns
   • perfectionist uses regex patterns

2. Internal patterns

   • oxfmt uses glob patterns
   • perfectionist uses regex patterns

3. Group selector syntax

   • oxfmt uses underscore (_)
   • perfectionist uses dash (-)
   • At least for side effects

---

Additionally, the documentation itself is not consistent regarding selectors and modifiers examples.

In the sorting guide:
https://oxc.rs/docs/guide/usage/formatter/sorting.html#sort-imports

The example shows:

{
  "sortImports": {
    "groups": [
      "type-import",
      ["value-builtin", "value-external"],
      "type-internal",
      "value-internal",
      ["type-parent", "type-sibling", "type-index"],
      ["value-parent", "value-sibling", "value-index"],
      "unknown"
    ]
  }
}

However, in the config reference:
https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html#sortimports-groups

The selectors are documented as:

Selectors (most to least important):

"type" — TypeScript type imports
"side_effect_style" — Side effect style imports
"side_effect" — Side effect imports
"style" — Style imports
"index" — Main file from the current directory
"sibling" — Modules from the same directory
"parent" — Modules from the parent directory
"subpath" — Node.js subpath imports
"internal" — Your internal modules
"builtin" — Node.js built-in modules
"external" — External modules installed in the project
"import" — Any import

Modifiers (most to least important):

"side_effect" — Side effect imports
"type" — TypeScript type imports
"value" — Value imports
"default" — Imports containing the default specifier
"wildcard" — Imports containing the wildcard ("* as") specifier
"named" — Imports containing at least one named specifier

But there's no mention or example of how to use modifiers. I think this can make it easy to miss how to use selectors with modifiers if you only read the reference and not the guide.

Additionally, this can lead to confusion given that modified selectors are dash-separated (type-import), while there are selectors that are underscore-separated (side_effect). Perfectionist uses dashes for everything.

---

I'm not certain if the solution is to improve the docs or modify oxfmt to be closer to the ESLint plugin.

[xandris]

i found this

oxc/crates/oxc_formatter/src/ir_transform/sort_imports/group_config.rs

Lines 48 to 61 in 44b5b35

	/// Parse a group name string into a GroupName.
	///
	/// Format: `(modifier-)*selector`
	///
	/// Since no selector or modifier name contains `-`,
	/// we can simply split by `-`: the last element is the selector,
	/// and all preceding elements are modifiers.
	///
	/// Examples:
	/// - "external" -> modifiers: (empty), selector: External
	/// - "type-external" -> modifiers: Type, selector: External
	/// - "value-builtin" -> modifiers: Value, selector: Builtin
	/// - "side_effect-import" -> modifiers: SideEffect, selector: Import
	/// - "side_effect-type-external" -> modifiers: SideEffect, Type, selector: External

so use kebab case with the modifiers, ending in a selector like side_effect-external. but it ought to be explained better in the docs