Course contentsShow
← TypeScript
Lesson 1105 of 1,79626. Modules in TypeScriptFree lesson

When Type-Only Imports Are Required

Understanding importsNotUsedAsValues and isolatedModules flags that enforce type-only imports.

When Type-Only Imports Are Required

You'll learn when TypeScript forces you to use import type instead of regular imports, and which compiler flags enforce this requirement.

The Core Idea

TypeScript has two compiler flags that can make type-only imports mandatory in certain situations: importsNotUsedAsValues and isolatedModules. These flags exist to ensure your code can be safely transpiled by tools that don't perform full type-checking (like Babel or esbuild), and to prevent subtle bugs where imports meant only for types accidentally affect your runtime behavior.

When these flags are enabled, TypeScript will show an error if you import something that's only used as a type without using the import type syntax.

The isolatedModules Flag

This flag tells TypeScript that each file will be compiled independently, without knowledge of other files. This mirrors how many modern build tools work. With isolatedModules: true, you must use import type when importing something that's only used in type positions:

// types.ts
export interface User {
  name: string;
  age: number;
}

// ❌ Error with isolatedModules: true
import { User } from './types';

const user: User = { name: 'Alice', age: 30 };

// ✅ Correct with isolatedModules
import type { User } from './types';

const user: User = { name: 'Alice', age: 30 };

Why? Build tools that process files independently can't tell whether User is a type or a value without analyzing types.ts. The type keyword makes it explicit.

The importsNotUsedAsValues Flag

This flag (deprecated in TypeScript 5.0 in favor of verbatimModuleSyntax) controls what happens with imports that only appear in type positions. It has three settings:

  • "remove" (default): Type-only imports are erased
  • "preserve": Imports are kept even if only used for types
  • "error": You get an error if you import something only used as a type without import type

With "error", you're forced to be explicit about type-only imports.

Mixed Imports and Requirements

When an import is used both as a type and as a value, you can use a regular import. But if you want to separate them for clarity or because of these flags:

// exports.ts
export class Logger { }
export interface LogConfig { }

// With strict flags, you might need:
import { Logger } from './exports';
import type { LogConfig } from './exports';

const config: LogConfig = { /* ... */ };
const logger = new Logger();

Or use inline type modifiers:

import { Logger, type LogConfig } from './exports';

Why These Flags Exist

These flags prevent scenarios where:

  1. Side effects from imports run unexpectedly
  2. Build tools generate incorrect output
  3. Circular dependencies cause issues
  4. Bundle size increases from unnecessary imports

They're especially important in projects using Babel, esbuild, or SWC for transpilation, since these tools strip types without full type-checking.

Key Takeaway: The isolatedModules and importsNotUsedAsValues flags can make import type syntax required rather than optional, ensuring your code is compatible with fast, single-file transpilers and preventing type imports from affecting runtime behavior.