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.
import type { Stats } from "node:fs"; import { type PathLike, readFileSync } from "node:fs";
Try it
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.
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
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
verbatimModuleSyntaxon, importing something that is purely a type withouttypeis an error. - An
import typestatement 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 typegives you only the type side, soinstanceofandnewfail, but annotations work.
Usage notes
- Turn on
verbatimModuleSyntaxin new projects. The rule becomes simple: imports withouttypealways stay, imports withtypealways go. - Use
import typewhen a statement imports only types, because it is removed entirely. An inlinetypemodifier 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.
isolatedModulesalso requiresexport typewhen 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 namedat link time. Marking ittypefixes it. - In older TypeScript, the
importsNotUsedAsValuesandpreserveValueImportsoptions tried to do this job;verbatimModuleSyntaxreplaced them.