Module System

Overview

Deno uses modern ES modules (ESM) as its standard module system. Unlike Node.js, Deno does not support CommonJS require() by default (except for Node.js compatibility mode). All modules use standard import and export syntax.

Deno’s module system is built on web standards, using the same import syntax as browsers.

Import Syntax

ES Module Imports

// Named imports
import { serve } from "https://deno.land/std@0.220.0/http/server.ts";

// Default imports
import express from "npm:express@4";

// Namespace imports
import * as path from "node:path";

// Type-only imports
import type { Handler } from "./types.ts";

// Dynamic imports
const module = await import("./dynamic.ts");

Import Maps

Import maps allow you to control module resolution:

{
  "imports": {
    "std/": "https://deno.land/std@0.220.0/",
    "@/": "./src/",
    "react": "npm:react@18.2.0"
  }
}

Module Resolution

From the source code (cli/module_loader.rs), Deno resolves modules in this order:

1. File Protocol

Local filesystem modules using absolute or relative paths:

// Relative imports
import { helper } from "./utils.ts";
import { config } from "../config.ts";

// Absolute file URLs
import { data } from "file:///home/user/project/data.ts";

All local imports must include file extensions. Deno does not support extensionless imports like "./utils".

2. HTTPS Protocol

Remote modules from any HTTPS URL:

import { assertEquals } from "https://deno.land/std@0.220.0/assert/mod.ts";
import { Application } from "https://deno.land/x/oak@v12.6.0/mod.ts";

Remote modules are:

Downloaded on first use
Cached locally in $DENO_DIR
Reused from cache on subsequent runs
Integrity-checked via lockfile

3. NPM Protocol

Node.js packages from npm registry:

// Package with version
import express from "npm:express@4.18.2";

// Latest version
import chalk from "npm:chalk";

// With subpath
import { parse } from "npm:yaml@2.3.1/parse";

4. JSR Protocol

Packages from the JavaScript Registry:

import { format } from "jsr:@std/datetime@0.220.0";
import { camelCase } from "jsr:@std/text/case";

5. Node Protocol

Node.js built-in modules:

import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { EventEmitter } from "node:events";

Module Loading Pipeline

Based on cli/module_loader.rs, the module loading process:

Resolution Steps

Parse specifier: Determine module type (file, https, npm, etc.)
Resolve to URL: Convert to canonical URL
Check permissions: Verify read/net permissions
Download/Load: Fetch from network or filesystem
Parse: Extract imports and exports
Build graph: Recursively load dependencies
Type check: Validate TypeScript (if enabled)
Compile: Transform TypeScript to JavaScript
Cache: Store compiled code
Execute: Run in V8

Module Graph

Deno builds a module graph before execution:

// main.ts imports:
import { a } from "./a.ts";  // which imports ./b.ts
import { x } from "./x.ts";  // which imports ./y.ts

// Module Graph:
// main.ts
//   ├── a.ts
//   │   └── b.ts
//   └── x.ts
//       └── y.ts

The graph ensures:

All dependencies are resolved before execution
Circular dependencies are handled correctly
Each module is loaded exactly once
Type checking covers all modules

Code Caching

From the module loader implementation, Deno caches:

Source Cache

Remote modules are cached in $DENO_DIR/deps:

$DENO_DIR/deps/
  https/
    deno.land/
      std@0.220.0/
        http/
          server.ts

Compiled Code Cache

Compiled JavaScript and type information:

// V8 code cache for ES modules
// Incremental compilation cache
// Source map cache

Cache Control

# Force reload from source
deno run --reload script.ts

# Reload specific modules
deno run --reload=https://deno.land/std script.ts

# Clear cache
deno cache --reload script.ts

Dynamic Imports

Deno supports dynamic imports with full type safety:

// Dynamic import with type
const module = await import("./module.ts");
module.exportedFunction();

// Conditional loading
if (useFeature) {
  const feature = await import("./feature.ts");
  feature.initialize();
}

// Runtime path
const modulePath = `./plugins/${pluginName}.ts`;
const plugin = await import(modulePath);

Dynamic imports require the same permissions as static imports. Remote dynamic imports need --allow-net, local ones need --allow-read.

Module Metadata

import.meta

Access module metadata:

// Current module URL
console.log(import.meta.url);
// => file:///home/user/project/main.ts

// Resolve relative to current module
const configPath = new URL("./config.json", import.meta.url);

// Check if module is main
if (import.meta.main) {
  console.log("Running as main module");
}

import.meta.resolve()

Resolve module specifiers:

// Resolve to absolute URL
const resolved = import.meta.resolve("./utils.ts");
console.log(resolved);
// => file:///home/user/project/utils.ts

// Resolve npm packages
const pkgPath = import.meta.resolve("npm:lodash");

TypeScript Module Resolution

Deno handles TypeScript imports natively:

// Import TypeScript directly
import { User } from "./types.ts";
import { Database } from "./db.ts";

// No need for .js extensions
// No tsconfig.json required
// No build step needed

Triple-Slash Directives

Type-only imports using triple-slash:

/// <reference types="./types.d.ts" />
/// <reference lib="deno.window" />

Module Types

JavaScript Modules

// .js or .mjs files
export function hello() {
  return "Hello, World!";
}

TypeScript Modules

// .ts or .mts files
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

JSON Modules

// Import JSON with type assertion
import config from "./config.json" with { type: "json" };

console.log(config.version);

WebAssembly Modules

// Import WebAssembly
const wasm = await WebAssembly.instantiateStreaming(
  fetch(new URL("./module.wasm", import.meta.url))
);

wasm.instance.exports.add(1, 2);

Best Practices

Always Use File Extensions

// Good
import { utils } from "./utils.ts";

// Bad - will not work
import { utils } from "./utils";

Pin Remote Module Versions

// Good - pinned version
import { serve } from "https://deno.land/std@0.220.0/http/server.ts";

// Bad - unpinned, can break
import { serve } from "https://deno.land/std/http/server.ts";

Use Import Maps for Large Projects

{
  "imports": {
    "@/": "./src/",
    "~/": "./",
    "std/": "https://deno.land/std@0.220.0/"
  }
}

Organize Barrel Exports

// mod.ts - barrel export
export * from "./user.ts";
export * from "./database.ts";
export { config } from "./config.ts";

Module Loading Errors

Common module resolution errors:

// Error: Missing file extension
import { x } from "./module";  // ❌
import { x } from "./module.ts";  // ✅

// Error: Relative import without ./
import { x } from "utils.ts";  // ❌
import { x } from "./utils.ts";  // ✅

// Error: Missing permissions
import { x } from "https://example.com/mod.ts";  // ❌ without --allow-net

Learn More

Explore TypeScript support to understand how Deno compiles TypeScript without configuration.

Getting Started

Core Concepts

Command Reference

Guides

Standard Library

Module System

Overview

Import Syntax

ES Module Imports

Import Maps

Module Resolution

1. File Protocol

2. HTTPS Protocol

3. NPM Protocol

4. JSR Protocol

5. Node Protocol

Module Loading Pipeline

Resolution Steps

Module Graph

Code Caching

Source Cache

Compiled Code Cache

Cache Control

Dynamic Imports

Module Metadata

import.meta

import.meta.resolve()

TypeScript Module Resolution

Triple-Slash Directives

Module Types

JavaScript Modules

TypeScript Modules

JSON Modules

WebAssembly Modules

Best Practices

Module Loading Errors

Learn More

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Command Reference

Guides

Standard Library

​Overview

​Import Syntax

​ES Module Imports

​Import Maps

​Module Resolution

​1. File Protocol

​2. HTTPS Protocol

​3. NPM Protocol

​4. JSR Protocol

​5. Node Protocol

​Module Loading Pipeline

​Resolution Steps

​Module Graph

​Code Caching

​Source Cache

​Compiled Code Cache

​Cache Control

​Dynamic Imports

​Module Metadata

​import.meta

​import.meta.resolve()

​TypeScript Module Resolution

​Triple-Slash Directives

​Module Types

​JavaScript Modules

​TypeScript Modules

​JSON Modules

​WebAssembly Modules

​Best Practices

​Module Loading Errors

Learn More

Build docs developers (and LLMs) love

Overview

Import Syntax

ES Module Imports

Import Maps

Module Resolution

1. File Protocol

2. HTTPS Protocol

3. NPM Protocol

4. JSR Protocol

5. Node Protocol

Module Loading Pipeline

Resolution Steps

Module Graph

Code Caching

Source Cache

Compiled Code Cache

Cache Control

Dynamic Imports

Module Metadata

import.meta

import.meta.resolve()

TypeScript Module Resolution

Triple-Slash Directives

Module Types

JavaScript Modules

TypeScript Modules

JSON Modules

WebAssembly Modules

Best Practices

Module Loading Errors