Native ES Modules with type="module"

Technical Deep Dive & Specifications

The 6 Core Behaviors of <script type="module">

When you add type="module" to a <script> tag, the browser switches from the classic script execution model to the ECMAScript Module (ESM) specification:

+---------------------------------------------------------------------------------------------------+
|                                  THE 6 PILLARS OF NATIVE ES MODULES                               |
+---------------------------------------------------------------------------------------------------+
|  1. DEFERRED BY DEFAULT:  Automatically behaves like `defer` (fetches in parallel, runs after DOM)|
|  2. STRICT MODE BY DEFAULT: `"use strict"` is permanently enabled; cannot be disabled.           |
|  3. TOP-LEVEL SCOPE:      Variables/functions are NOT attached to `window`.                       |
|  4. CORS ENFORCEMENT:     Cross-origin modules MUST serve valid CORS headers; file:// is blocked. |
|  5. TOP-LEVEL AWAIT:      You can `await` promises directly in module root without an async wrapper|
|  6. SINGLETON EXECUTION:  A module is fetched and executed ONCE, even if imported 50 times.       |
+---------------------------------------------------------------------------------------------------+

1. Automatic Deferral

You do not need to add the defer attribute to <script type="module">. The browser automatically fetches the module and its entire dependency graph in parallel in the background, executing them in document order after HTML parsing finishes and before DOMContentLoaded.

2. Top-Level await

In classic scripts, await was only valid inside an async function. In ES modules, top-level await is natively supported:

<script type="module">
  // Top-level await is 100% valid!
  const response = await fetch('/api/user');
  const user = await response.json();
  console.log('Logged in as:', user.name);
</script>

3. Module Singleton Execution

If moduleA.js and moduleB.js both contain import { db } from './database.js', the browser fetches database.js exactly once, executes it once, and shares the same live module export instance between both consumers.

Import Maps (<script type="importmap">)

Historically, browsers required relative or absolute URLs for imports:

// Valid in browsers:
import { format } from './utils/date.js';
import { Chart } from 'https://cdn.example.com/chart.js';

// INVALID in classic browser ESM (Bare Specifier):
import { format } from 'date-fns'; // ❌ TypeError: Failed to resolve module specifier

The Import Maps specification allows developers to declare alias mappings directly in HTML:

<script type="importmap">
{
  "imports": {
    "lodash": "https://cdn.jsdelivr.net/npm/[email protected]/lodash.js",
    "services/": "/src/services/",
    "@components/": "/src/ui/components/"
  }
}
</script>

<script type="module">
  // Now bare specifiers work natively in the browser!
  import { debounce } from 'lodash';
  import { AuthService } from 'services/auth.js';
</script>

⚠️ Strict Rule: An <script type="importmap"> element must appear before any <script type="module"> tags in the HTML document.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 12–18 (<script type="importmap">): Maps the bare specifier "formatter" to an in-memory ESM module exporting formatCurrency().
• Line 21 (<script type="module">): Starts an ES module script. Automatically runs with deferred timing and strict mode.
• Line 22 (import { formatCurrency } from 'formatter'): Cleanly imports the function using the import map.
• Lines 27–31 (await new Promise(...)): Demonstrates Top-Level await directly at the root level of the script.
• Line 34 (const accountBalance): Scoped strictly to this module. Line 43 logs window.accountBalance is -> undefined, proving zero global namespace pollution.

Expected Browser Render Output

Banking Overview

[ Alex Mercer ]
Account Balance: $14250.75

(DevTools Console Output):
[Module Script]: Importing and executing...
[Module Script]: window.accountBalance is -> undefined