Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

Type-only imports in TypeScript

Reference for TypeScript type-only imports: import type, inline type modifiers, import() types, errors TS1361 and TS1484, and verbatimModuleSyntax.

A type-only import brings in a name that exists only for the type checker. It is written import type { Name } from "./m.js", or with an inline modifier: import { type Name, value } from "./m.js". The compiler erases import type completely, so the imported module is not even loaded at run time because of that line.

Plain import is also erased when every imported name is used only as a type, but that only works if the compiler can see the whole program. Tools that transpile one file at a time, such as esbuild, SWC and Node's built-in type stripping, cannot know which names are types, so you tell them with the type keyword. Anything marked type can be used in type positions only.

TypeScript
import type { Stats } from "node:fs";
import { type PathLike, readFileSync } from "node:fs";

Try it

TypeScript Using a type-only import as a value (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Mixing values and types in one import

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

The first example stops with main.ts(7,17): error TS1361: 'EventEmitter' cannot be used as a value because it was imported using 'import type'. The class exists at run time, but this import asked for its type only. Using it as the parameter type is fine.

Syntax

TypeScript
import type { A, B } from "./m.js";        // named, all type-only
import type Default from "./m.js";         // default
import type * as ns from "./m.js";         // namespace
import { type A, value } from "./m.js";    // inline modifier
export type { A } from "./m.js";           // see Re-exports
type T = import("./m.js").A;               // import type expression
Form Description
import type { A } Whole statement is removed from the output.
import { type A, b } Only A is type-only. The statement stays as import { b }; if nothing is left it becomes import {} from "m", which still runs the module for side effects.
import("m").A A type that points into a module without any import statement. Erased.

Edge cases and errors:

  • TS1361: a type-only name is used as a value (see above).
  • TS1484: with verbatimModuleSyntax on, importing something that is purely a type without type is an error.
  • An import type statement cannot combine a default import and named imports in one clause (import type A, { B } is an error); write two statements.
  • A class is both a type and a value. import type gives you only the type side, so instanceof and new fail, but annotations work.

Usage notes

  • Turn on verbatimModuleSyntax in new projects. The rule becomes simple: imports without type always stay, imports with type always go.
  • Use import type when a statement imports only types, because it is removed entirely. An inline type modifier is better when you mix values and types from the same module.
  • Type-only imports are safe for circular dependencies: they never create a run-time cycle.
  • isolatedModules also requires export type when re-exporting a type, since a single-file tool cannot check that.
  • Node's type stripping fails when an ordinary import names something that is only a type, with does not provide an export named at link time. Marking it type fixes it.
  • In older TypeScript, the importsNotUsedAsValues and preserveValueImports options tried to do this job; verbatimModuleSyntax replaced them.