TypeScript "TS1484: ... is a type and must be imported using a type-only import"

By Daniel Zoghalchali·Latchkey

verbatimModuleSyntax makes TypeScript emit imports/exports verbatim, eliding nothing. A name used only as a type must be imported with import type, otherwise tsc would emit a runtime import of something that has no runtime value - TS1484.

What this error means

tsc (or the framework build) fails with TS1484: '<Name>' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled. It appears after enabling the option, naming each value-imported type.

src/api.ts:1:10 - error TS1484: 'User' is a type and must be imported using
a type-only import when 'verbatimModuleSyntax' is enabled.

1 import { User, fetchUser } from './user'
           ~~~~

Diagnose it: which tsconfig and which compiler?

A TypeScript error that appears only in CI usually means the runner is compiling with a different config or a different compiler version than your editor. Your editor uses the workspace TypeScript and the nearest tsconfig.json; CI uses whatever the lockfile resolved and whatever config the build script names.

# what CI will actually use
npx tsc --version
npx tsc --showConfig | head -40

# which files are in the program (a missing include is a common cause)
npx tsc --listFiles | wc -l

# type-check only, no emit, same as most CI gates
npx tsc --noEmit

Common causes

A type imported as a value

Under verbatimModuleSyntax the compiler does not strip type-only imports automatically. Importing a type with a plain import { Type } would generate a runtime import of a nonexistent value, so tsc requires import type.

Mixed type/value imports from one module

A single import { Type, value } mixes a type and a runtime value; the type part must be marked type (inline or in a separate statement).

How to fix it

Use import type (or inline type)

Mark type-only imports so nothing runtime is emitted for them.

import type { User } from './user'
import { fetchUser } from './user'
// or inline:
import { type User, fetchUser } from './user'

Autofix across the codebase

# typescript-eslint can rewrite these automatically
npx eslint . --fix --rule '{"@typescript-eslint/consistent-type-imports":"error"}'

Pin the compiler so unrelated updates cannot break the gate

TypeScript adds errors in minor releases. An unpinned compiler turns a routine dependency update into a red build on code nobody touched, which is the most common false alarm in a TypeScript CI pipeline.

// package.json
{
  "devDependencies": {
    "typescript": "5.6.3"   // exact, not ^5.6.3
  }
}

How to prevent it

• Use import type for type-only imports.
• Enable @typescript-eslint/consistent-type-imports with autofix.
• Turn on verbatimModuleSyntax early so import-style issues surface in dev.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation