Course contentsShow
← TypeScript
Lesson 1762 of 1,79640. The Future of TypeScriptFree lesson

Import Assertions and Type-Only Imports

Import assertions for JSON/CSS modules and how TypeScript's type-only imports anticipate module types.

Import Assertions and Type-Only Imports

What you'll learn: How TypeScript handles emerging module types like JSON and CSS through import assertions, and how type-only imports prepare for a future where module types are explicitly declared.

The Module Type Problem

As JavaScript evolves, we're importing more than just code. JSON modules, CSS modules, WebAssembly—each has different runtime characteristics. Import assertions provide a way to tell the runtime what kind of module you're importing, preventing security issues and enabling proper handling.

Meanwhile, TypeScript has always had a challenge: distinguishing imports that exist only for types versus those needed at runtime. As bundlers get smarter and JavaScript itself moves toward explicit type syntax, TypeScript's type-only imports become increasingly important.

Import Assertions: Specifying Module Types

Import assertions use the assert keyword (evolving to with in newer proposals) to declare module type expectations:

// Importing JSON with an assertion
import config from "./config.json" assert { type: "json" };

// TypeScript knows config is the parsed JSON structure
const apiUrl: string = config.apiUrl;

// CSS modules (when supported)
import styles from "./button.css" assert { type: "css" };

These assertions don't just help TypeScript—they tell the runtime what to expect, creating a security boundary. Without them, a malicious server could send JavaScript when you expected JSON.

Type-Only Imports: The import type Syntax

Type-only imports explicitly mark what exists solely at compile-time:

import type { UserProfile } from "./types";

// This import disappears entirely after compilation
// No runtime module loading, no bundle bloat

This matters because TypeScript can't always determine if an import is type-only. Explicit import type guarantees erasure and helps bundlers tree-shake more aggressively.

Why This Matters for the Future

As TC39 considers adding type syntax directly to JavaScript, these patterns establish clear boundaries between type-space and value-space. Import assertions prepare TypeScript for a world where module types are standardized, while type-only imports anticipate explicit type markers in the language itself.

Key Takeaway: Import assertions declare what you're importing (JSON, CSS), while type-only imports declare why you're importing (types only), both preparing TypeScript for a future of explicit module and type handling.