oxc-project/oxc · warning · OxcDiagnostic

Prefer using a top-level type-only import instead of inline

Error message

Prefer using a top-level type-only import instead of inline type specifiers when there are only type imports.

What it means

The `prefer-top-level-if-only-type-imports` mode of `import/consistent-type-specifier-style`: when every specifier in an import statement is a type, the statement must be a top-level `import type`; statements mixing type and value specifiers may keep inline specifiers.

Source

Thrown at crates/oxc_linter/src/rules/import/consistent_type_specifier_style.rs:47

    .with_label(span)
}

fn consistent_type_specifier_style_diagnostic(span: Span, mode: &Mode) -> OxcDiagnostic {
    let (warn_msg, help_msg) = match mode {
        Mode::Inline => (
            "Prefer using inline type specifiers instead of a top-level type-only import.",
            "Replace top‐level import type with an inline type specifier.",
        ),
        Mode::TopLevel => (
            "Prefer using a top-level type-only import instead of inline type specifiers.",
            "Replace inline type specifiers with a top‐level import type statement.",
        ),
        Mode::TopLevelIfOnlyTypeImports => (
            "Prefer using a top-level type-only import instead of inline type specifiers when there are only type imports.",
            "Replace inline type specifiers with a top‐level import type statement.",
        ),
    };
    OxcDiagnostic::warn(warn_msg).with_help(help_msg).with_label(span)
}

#[derive(Debug, Default, PartialEq, Clone, Serialize, Deserialize, JsonSchema)]
enum Mode {
    /// Prefer `import type { Foo } from 'foo'` for type imports.
    #[default]
    #[serde(rename = "prefer-top-level")]
    TopLevel,
    /// Prefer `import { type Foo } from 'foo'` for type imports.
    #[serde(rename = "prefer-inline")]
    Inline,
    /// Prefer `import type { Foo } from 'foo'` when all named imports are types, but allow
    /// `import { type Foo, bar } from 'foo'` when value imports are present.
    #[serde(rename = "prefer-top-level-if-only-type-imports")]
    TopLevelIfOnlyTypeImports,
}

#[derive(Debug, Default, Clone, Serialize, Deserialize)]

View on GitHub (pinned to e1e7af627c)

Solutions

1. Rewrite all-type statements as `import type { Foo, Bar } from 'foo';`
2. Leave genuinely mixed type/value statements as they are — this mode permits inline there
3. Use `oxlint --fix` to convert every all-type statement in one pass

Example fix

// before — every specifier in the statement is a type
import { type Foo, type Bar } from 'foo';

// after
import type { Foo, Bar } from 'foo';

// .oxlintrc.json
{
  "plugins": ["import"],
  "rules": { "import/consistent-type-specifier-style": ["warn", "prefer-top-level-if-only-type-imports"] }
}
// CI gate: npx oxlint src/

When it happens

Trigger: `import { type Foo, type Bar } from 'foo';` with the rule configured as prefer-top-level-if-only-type-imports and a non-declaration-file source.

Common situations: Teams that want the erasure safety of top-level type imports without forcing statement splits on mixed imports; gradual migrations away from inline style.

Related errors

• Prefer using inline type specifiers instead of a top-level t
• Prefer using a top-level type-only import instead of inline
• Type imports from declaration files must use top-level `impo
• Export statements should appear at the end of the file
• Type can be trivially inferred from the initializer

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