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.