feat(oxfmt/sort-imports): support custom groups by nilptr · Pull Request #17576 · oxc-project/oxc

nilptr · 2026-01-02T01:02:29Z

Authorship & Use of AI

All code changes in this pull request are completed by a human (myself).
ChatGPT is used only to assist with writing comments and this PR description.

Commit Structure

The changes are split into small, meaningful commits.
Each commit should be reviewable independently.

Current State of the Implementation

For easier comparison, I forked actual and made a few auxiliary changes on a separate branch nilptr/feat/oxfmt-custom-groups.

The auxiliary changes include:

Upgraded oxfmt to address the incompatible binding API.
Updated eslint.config.mjs to lint and fix .ts files.
Updated .oxfmtrc to enable experimentalSortImports, keeping it consistent with eslint.config.mjs.

How to Compare?

Clone git@github.com:nilptr/actual.git and check out nilptr/feat/oxfmt-custom-groups branch.
Run yarn install
Run NAPI_RS_NATIVE_LIBRARY_PATH=/path/to/binding.node yarn fmt:oxfmt

The native binding can be obtained in one of the following ways:
- Download the oxfmt.darwin-arm64.node.zip built by me (if you trust it, or scan it with VirusTotal).
- Build it by yourself: clone my repo, run pnpm build, and locate the .node binding file under apps/oxfmt/src-js.
Inspect the results with git diff — the diff shows the differences between perfectionist and oxfmt

Observed Differences

There are 9 differences in total:

4 differences are unrelevant to experimentalSortImports. (be the way, they are introduced after I rebased main branch)
5 differences are relevant to experimentalSortImports, but are not caused by the group-matching logic, which is the focus of this PR.
- 4 of them are blank lines after side-effect imports being removed
- 1 of them is the wrong ImportLineMetadata.source

I believe we can start review now.
While the review is ongoing, I will also try to see whether the observed differences can be fixed in this PR.

codspeed-hq · 2026-01-02T12:45:47Z

CodSpeed Performance Report

Merging this PR will not alter performance

_{Comparing nilptr:nilptr/feat/sort-imports-custom-groups (92e8eae) with main (a0b3721)}

Summary

✅ 38 untouched benchmarks
⏩ 7 skipped benchmarks¹

7 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

leaysgur · 2026-01-05T01:50:02Z

Thank you~. Great work! 👏🏻
(And sorry for the late review..., btw Happy New Year!)

I'll review the changes and go through from now.

I will also try to see whether the observed differences can be fixed in this PR.

If possible, could you submit a separate PR for these?

crates/oxc_formatter/src/ir_transform/sort_imports/options.rs

crates/oxc_formatter/src/ir_transform/sort_imports/compute_metadata.rs

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

crates/oxc_formatter/src/oxfmtrc.rs

leaysgur

Thanks again. ✨

Actually, index-type and sibling-type are invalid groups in perfectionist.

OK, let's remove it.

Regarding this, I'll leave it up to you whether to address it in this PR or create a separate one.

crates/oxc_formatter/src/oxfmtrc.rs

crates/oxc_formatter/src/ir_transform/sort_imports/compute_metadata.rs

crates/oxc_formatter/src/ir_transform/sort_imports/options.rs

crates/oxc_formatter/src/oxfmtrc.rs

#17576 (comment)

leaysgur · 2026-01-08T01:22:36Z

NOTE:

I'll take care of resolving CI/Lint errors, so you don't need to worry about it
For CI/Test, you need to
- crates/oxc_formatter: cargo t
- (root): cargo t -p website_formatter
- Then, cargo insta accept
When you are ready for a review, just press the Re-request review button

Preparation for #17576 ``` error: large size difference between variants --> apps/oxfmt/src/core/config.rs:51:1 | 51 | / pub enum ResolvedOptions { 52 | | /// For JS/TS files formatted by oxc_formatter. 53 | | / OxcFormatter { 54 | | | format_options: FormatOptions, 55 | | | /// For embedded language formatting (e.g., CSS in template literals) 56 | | | external_options: Value, 57 | | | insert_final_newline: bool, 58 | | | }, | | |_____- the largest variant contains at least 281 bytes ... | 66 | | / ExternalFormatterPackageJson { 67 | | | external_options: Value, 68 | | | sort_package_json: Option<sort_package_json::SortOptions>, 69 | | | insert_final_newline: bool, 70 | | | }, | | |_____- the second-largest variant contains at least 75 bytes 71 | | } | |___^ the entire enum is at least 288 bytes | = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.92.0/index.html#large_enum_variant = note: `-D clippy::large-enum-variant` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::large_enum_variant)]` help: consider boxing the large fields or introducing indirection in some other way to reduce the total size of the enum | 54 - format_options: FormatOptions, 54 + format_options: Box<FormatOptions>, | ```

…onist

nilptr · 2026-01-18T09:50:36Z

Many tests involving customGroups are primarily testing the sorting options (such as type, order, etc.) inside a custom group, rather than the grouping logic itself.
Those behaviors are not implemented yet and outside the scope of this PR, so I just added 2 of them.
Besides that, because type: "line-length" is not supported yet, I made some adjustments to the test cases.

leaysgur · 2026-01-18T13:13:43Z

Thanks again!

About their tests, everything is as expected, and since we've been modifying and porting test cases all along. 😅 So, it should be fine for now.

I plan to review it again tomorrow morning and merge it. 👍🏻

leaysgur

🚀

nilptr requested review from Dunqing and camc314 as code owners January 2, 2026 01:02

github-actions bot added A-linter Area - Linter A-formatter Area - Formatter C-enhancement Category - New feature or request labels Jan 2, 2026

nilptr force-pushed the nilptr/feat/sort-imports-custom-groups branch from 00ea51b to c405a09 Compare January 2, 2026 01:05

camc314 assigned leaysgur and Dunqing Jan 2, 2026

This comment was marked as resolved.

Sign in to view

Dunqing removed their assignment Jan 3, 2026

Dunqing requested review from leaysgur and removed request for Dunqing and camc314 January 3, 2026 15:32

leaysgur requested changes Jan 5, 2026

View reviewed changes

nilptr force-pushed the nilptr/feat/sort-imports-custom-groups branch 2 times, most recently from f74914b to 73ff4ab Compare January 7, 2026 01:11

This comment was marked as resolved.

Sign in to view

leaysgur requested changes Jan 7, 2026

View reviewed changes

nilptr force-pushed the nilptr/feat/sort-imports-custom-groups branch from 73ff4ab to 1a3d3de Compare January 8, 2026 01:04

nilptr mentioned this pull request Jan 8, 2026

feat(formatter/sort_imports): Update NODE_BUILTINS modules #17771

Merged

leaysgur pushed a commit that referenced this pull request Jan 8, 2026

feat(formatter/sort_imports): Update NODE_BUILTINS modules (#17771)

539b350

#17576 (comment)

leaysgur mentioned this pull request Jan 8, 2026

refactor(oxfmt): Use Box<FormatOptions> for ResolvedOptions #17772

Merged

nilptr force-pushed the nilptr/feat/sort-imports-custom-groups branch from 1a3d3de to 0f369cd Compare January 11, 2026 15:49

github-actions bot added the A-cli Area - CLI label Jan 11, 2026

nilptr mentioned this pull request Jan 11, 2026

fix(formatter/sort-imports): hard line inside multiline import leads to incorrect results #17880

Merged

nilptr requested a review from leaysgur January 12, 2026 03:42

nilptr added 18 commits January 18, 2026 17:09

refactor(oxfmt): align selector and modifier definition with perfecti…

ebe955e

…onist

refactor(oxfmt): GroupName parse logic

a2c817e

feat(oxfmt): make GroupName sortable

7e68139

feat(oxfmt): add GroupMatcher

8f4119a

feat(oxfmt): delete ImportGroupMatcher & use GroupMatcher

552920a

chore(oxfmt): delete dead code

f02a10a

chore: fix errors

1997421

fix(oxfmt/sort-imports): ImportPathKind::Parent

e3b13ac

chore: fix lint errors

7a4800b

refactor(oxfmt): reverse dependency

08d65d9

refactor(oxfmt): remove ImportModifier::Require

13aff03

refactor(oxfmt): pass ImportPathKind by ref

7405cd6

refactor(oxfmt): unify CustomGroupDefinition

cdf57b4

chore(oxfmt/sort-imports): remove invalid test cases

a22859b

fix(oxfmt/sort-imports): incorrect GroupName sort order

20bffa4

feat(oxfmt/sort-imports): add custom group test cases

4867aaf

chore(oxfmt/sort-imports): fix incorrect comment

d4e49a0

chore(oxfmt/sort-imports): cargo insta accept

8381619

nilptr force-pushed the nilptr/feat/sort-imports-custom-groups branch from bb9fef7 to 8381619 Compare January 18, 2026 09:18

nilptr added 2 commits January 18, 2026 17:28

chore(oxfmt/sort-imports): update comment

6262e0b

chore(oxfmt/sort-imports): cargo insta accept

84ed9ad

Merge branch 'main' into nilptr/feat/sort-imports-custom-groups

52971fe

leaysgur added 2 commits January 19, 2026 09:55

Update docs

da3ec0e

Fix up

92e8eae

leaysgur approved these changes Jan 19, 2026

View reviewed changes

leaysgur merged commit 984d5c1 into oxc-project:main Jan 19, 2026
27 checks passed

leaysgur mentioned this pull request Jan 19, 2026

[$200 bounty] formatter: experimentalSortImports.customGroups #17076

Closed

Boshen mentioned this pull request Jan 19, 2026

release(apps): oxlint v1.40.0 && oxfmt v0.25.0 #18223

Merged

Uh oh!

Comments

Conversation

nilptr commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Authorship & Use of AI

Commit Structure

Current State of the Implementation

How to Compare?

Observed Differences

Uh oh!

codspeed-hq bot commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging this PR will not alter performance

Summary

Footnotes

Uh oh!

This comment was marked as resolved.

leaysgur commented Jan 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

leaysgur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

leaysgur commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nilptr commented Jan 18, 2026

Uh oh!

leaysgur commented Jan 18, 2026

Uh oh!

leaysgur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nilptr commented Jan 2, 2026 •

edited

Loading

codspeed-hq bot commented Jan 2, 2026 •

edited

Loading

leaysgur commented Jan 8, 2026 •

edited

Loading