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.

What it means

The default `prefer-top-level` mode of `import/consistent-type-specifier-style`: inline type specifiers must be lifted into a dedicated top-level `import type` statement, which erases cleanly under TypeScript's `isolatedModules`/verbatim semantics. Declaration-file imports are already required to be top-level.

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. Split into `import type { Foo } from 'foo';` plus `import { bar } from 'foo';`
2. Run `oxlint --fix` — the fixer regenerates both statements
3. If the inline style is preferred repo-wide, switch the rule to prefer-inline instead

Example fix

// before
import { type Foo, bar } from 'foo';

// after
import type { Foo } from 'foo';
import { bar } from 'foo';

// .oxlintrc.json (default mode)
{
  "plugins": ["import"],
  "rules": { "import/consistent-type-specifier-style": "warn" }
}
// CI gate: npx oxlint src/

When it happens

Trigger: `import { type Foo, bar } from 'foo';` with the rule at default settings (or explicitly prefer-top-level) and a non-declaration-file source.

Common situations: Codebases adopting isolatedModules or VerbatimModuleSyntax where inline specifier churn matters; mixed styles after team merges; default-enabled configs flagging older inline syntax.

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/2c7c4fc779d33433. Report an issue: GitHub.