What causes "Imports should be sorted alphabetically." in oxc-project/oxc?

Sort the adjacent declarations alphabetically.

oxc-project/oxc · info · OxcDiagnostic

Imports should be sorted alphabetically.

Error message

Imports should be sorted alphabetically.

What it means

oxlint `eslint/sort-imports`: consecutive import declarations of the same syntax kind are out of alphabetical order by first member/alias name (then source). `sort_imports_alphabetically_diagnostic` (sort_imports.rs:32) emits 'Imports should be sorted alphabetically.' This is the within-kind ordering check of the rule described in its doc block: imports are sorted first by member syntax, then alphabetically.

Source

Thrown at crates/oxc_linter/src/rules/eslint/sort_imports.rs:32

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::{
    context::LintContext,
    rule::{DefaultRuleConfig, Rule},
};

fn unexpected_syntax_order_diagnostic(
    curr_kind: &ImportKind,
    prev_kind: &ImportKind,
    span: Span,
) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!("Expected '{curr_kind}' syntax before '{prev_kind}' syntax."))
        .with_label(span)
}

fn sort_imports_alphabetically_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Imports should be sorted alphabetically.").with_label(span)
}

fn sort_members_alphabetically_diagnostic(name: &str, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!(
        "Member '{name}' of the import declaration should be sorted alphabetically."
    ))
    .with_label(span)
}

#[derive(Debug, Default, Clone, Deserialize)]
pub struct SortImports(Box<SortImportsOptions>);

#[derive(Debug, Default, Clone, JsonSchema, Deserialize)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct SortImportsOptions {
    /// When `true`, the rule ignores case-sensitivity when sorting import names.
    ignore_case: bool,
    /// When `true`, the rule ignores the sorting of import declarations (the order of `import` statements).

View on GitHub (pinned to e1e7af627c)

Solutions

Sort the adjacent declarations alphabetically.
Separate logically distinct groups with a blank line and set `allowSeparatedGroups: true` so each group sorts independently.
Set `ignoreCase: true` if case differences ('API' vs 'api') cause churn.
Set `ignoreDeclarationSort: true` to disable declaration-order checking.

Example fix

// before
import { zebra } from 'animals.js';
import { apple } from 'fruits.js';
import { banana } from 'fruits.js';

// after
import { apple } from 'fruits.js';
import { banana } from 'fruits.js';
import { zebra } from 'animals.js';

Defensive patterns

Strategy: validation

Prevention

Insert new imports in sorted position rather than appending at the end of the block.
After merge conflicts in import blocks, run the linter before committing.
Set `allowSeparatedGroups: true` and group by module type — groups then sort independently and churn drops.

When it happens

Trigger: `import b from 'b.js'; import a from 'a.js';` — two adjacent declarations of the same ImportKind whose compared names invert the sort. Comparison uses the first member or alias name; `ignoreCase` and `allowSeparatedGroups` options alter it.

Common situations: Merge conflicts resolved by keeping both imports in the wrong order; new imports prepended rather than inserted in order; enabling the rule on legacy files.

Related errors

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/f877d3b3ab134a5e. Report an issue: GitHub.