Dynamic import & top-level await

Load a module only when you need it

In the last lessons, you wrote import at the top of a file. That is a static import. "Static" means fixed: the browser loads those files before your code runs. That is right for code you always need.

Some code is not always needed. Think of a chart screen, a text editor, an admin page, or a second language. Many visitors never open them. If the page loads them at the start, the first screen is slower for everyone.

Dynamic import solves this. You write import(specifier), like a function call. Here is how it works:

• It runs only when your code reaches that line.
• The specifier is the string that names the file, like "./charts.js". Your code can build that string while the program runs.
• It returns a Promise. When the file is ready, the promise gives you the module's exports.
• It works in normal scripts and in modules.

This lesson covers these tools, in this order:

• import(), which loads a module when you ask.
• Code splitting, which keeps extra code out of the first download.
• Top-level await, which lets a module wait before it is ready.
• import.meta and import.meta.resolve(), which tell a module where it lives.
• import defer and import source, two new forms that are not ready for everyday use yet.

Read the code first. import() does not hand you the exports straight away. It hands you a promise, and await waits for it. The promise then gives you the module namespace object. That is a read-only object with one property for each export of the module.

1const menu = await import("./menu.js");2console.log(menu.default);3console.log(menu.price);

In plain words, line by line:

1. Line 1 loads menu.js and waits. Then it saves the module namespace object in menu.
2. Line 2 reads menu.default. A default export is just a property named default. It prints tea.
3. Line 3 reads the named export price. It prints 3.

1const pending = import("counter");2console.log(pending instanceof Promise);3const counter = await pending;4console.log(counter.next());5const again = await import("counter");6console.log(again === counter);7await import("broken");

The lab shows four things to remember:

1. The promise exists right away, before the module is ready. So you can show a "Loading" message while you wait, like with any promise from the Promises lesson.
2. The promise gives you the namespace object, not the default export. To read a default export, write module.default.
3. JavaScript keeps each module after it runs once. This is the module cache. A second import of the same URL gives you the same module, and its code does not run again. So its variables are shared, whether you load it with import or with import().
4. If the file is missing, has a syntax error, or throws an error while it runs, the promise rejects, which means it fails. Put await import(...) inside try/catch to handle that.

1const loadLocale = {2  en: () => import("./locales/en.js"),3  hi: () => import("./locales/hi.js"),4};5const language = "en";6const locale = await loadLocale[language]();7console.log(locale.greeting);

In plain words, line by line:

1. Lines 1 to 4 make an object called loadLocale. It lists every language file the app may load. Each value is a small function that imports one file.
2. Line 5 sets language to "en".
3. Line 6 calls only the English function, so only ./locales/en.js is loaded.
4. Line 7 prints Hello.

Each file path is written out in full. So a bundler can find both files and make a separate file for each one.

1try {2  await import("./broken.js");3} catch (error) {4  console.log(error.message);5}

broken.js throws an error while it runs. So the import on line 2 rejects. The catch block on line 3 catches the error, and line 4 prints feature failed. Without try/catch, nothing would handle the error.

import() is part of the JavaScript language. Code splitting is what a bundler does with it. The bundler puts each dynamically imported module into its own file, called a chunk. Then the browser loads:

• the small main part of the app, called the shell, right away;
• each feature chunk later, when someone opens that feature.

This site works this way. Each lesson page is its own chunk. So opening this lesson does not load the code for every other lesson.

1const loaded = new Set(["shell"]);2let bytes = 42;3 4async function openFeature(name) {5  if (!loaded.has(name)) {6    bytes = bytes + featureBytes[name];7    loaded.add(name);8  }9  return name + " ready";10}

1async function openCharts(wasClicked) {2  if (!wasClicked) return "waiting";3  const charts = await import("./charts.js");4  return charts.open();5}6 7console.log(await openCharts(false));8console.log(await openCharts(true));

In plain words, line by line:

1. Line 7 calls openCharts(false), which means "no click yet". Line 2 returns "waiting", and nothing is imported.
2. Line 8 calls openCharts(true), which acts like a click.
3. Line 3 loads charts.js and waits for it.
4. Line 4 calls its open() export, so line 8 prints chart opened.

A real button would show a "Loading" message while line 3 waits.

1<link rel="modulepreload" href="./charts.js">2<script type="module" src="./app.js"></script>

A modulepreload link asks the browser to download a module early and get it ready. It does not run the module. import() still decides when the module runs. Use it only when the user will probably open that feature soon. If they don't, you downloaded bytes for nothing.

The next replay shows two choices, step by step. Try each one:

• Load on click downloads nothing until the user clicks.
• Preload on hover starts the download when the pointer moves over the button. It costs bytes earlier, but the click may feel instant.

1const app = bootShell();Run2button.addEventListener("click", async () => {3  const charts = await import("./charts.js");4  charts.renderDashboard();5});

Normally you can use await only inside an async function. Top-level await means writing await directly in a module, outside any function. It works only in modules, not in normal scripts.

When a module uses it, the module pauses at that line. Then:

• Modules that import it wait until it finishes.
• Modules that don't import it keep going.

1const settings = await fetch("./settings.json").then((response) => response.json());2export const theme = settings.theme;3console.log(theme);

Line 1 fetches settings.json and waits for the answer. Line 2 exports theme from those settings. So a module that imports theme always gets a ready value. If the fetch fails, that import fails instead. This example needs a real settings.json file, so here you can only read it.

1// config.js2const started = performance.now();3await new Promise((resolve) => setTimeout(resolve, 350));4export const config = "ready after " + Math.round(performance.now() - started) + "ms";5 6// app.js7import { config } from "config";8post("app can run only after config: " + config);9 10// sibling.js11post("sibling module ran without waiting for config");

Use top-level await with care:

• It is a good fit for one-time setup that every export of the module needs.
• It is a bad fit for a small helper file that every page imports. A slow wait there holds up every page that uses it.

Sometimes a module needs to know where its own file is. import.meta is an object with facts about the current module. The browser or Node fills it in. Its most useful property is import.meta.url: the full URL of the current module file.

Say an image sits in the same folder as your module. Write new URL("./tea.svg", import.meta.url) to get its full URL. new URL(name, base) joins a file name to a base address. The URL objects lesson covers it in depth.

1const iconUrl = new URL("./tea.svg", import.meta.url);2console.log(iconUrl.href.endsWith("/tea.svg"));

Line 1 uses this module's URL as the base. So the result stays right even when the page URL changes. Line 2 prints true, because the full URL ends in /tea.svg. The same trick works for workers and other files near the module.

import.meta.resolve(specifier) answers one question: "What full URL would this name point to from this module?" It only works out the URL. It does not load the file.

1console.log(import.meta.url);2console.log(import.meta.resolve("./helper.js"));3console.log(import.meta.resolve("missing-package"));

import defer and import source are proposals

TC39 is the group that decides on new JavaScript features. A proposal is an idea for a new feature. Each proposal moves through stages from 0 to 4. At Stage 4, it becomes part of JavaScript.

The TC39 list puts two module proposals at Stage 3: Deferring Module Evaluation and Source Phase Imports. Stage 3 means the design is nearly done and browsers are trying it out. It does not mean every browser runs it today. So the code below is for reading only.

1// Display-only proposals, not runnable lesson code2import defer * as charts from "./heavy-charts.js";3import source parser from "./parser.wasm";4 5// Today: use import() or your bundler's documented features instead.

What each line is for:

• Line 2, import defer, loads the module and links it now. But it waits to run the module until your code first reads something from charts.
• Line 3, import source, gives you the module before it runs, such as a WebAssembly module. WebAssembly is a fast, compiled kind of code that browsers can run.

Normal browsers may not run either line without extra tools. Today, the tool that works everywhere is still import().

The table compares the three tools. Read each row across: when the tool does its work, what you get, and when to use it.

Then try the sorter. Use these rules:

• The first screen can't work without it? Use a static import.
• A click or a setting chooses it later? Use import().
• The module's own exports are not usable until setup finishes? Think about top-level await.

Where you'll use this

You'll use import() wherever a feature is useful but not always needed. Common cases:

• Pages: settings pages, admin tools, and dashboards should not slow down the home page.
• Heavy widgets: charts, text editors, maps, code highlighters, and video tools can load after a click.
• Language files: load only the language the user picked.

1button.addEventListener("click", async () => {2  button.disabled = true;3  const { openEditor } = await import("./editor-panel.js");4  openEditor(document.querySelector("#draft"));5});6 7async function loadLocale(language) {8  return import("./locales/" + language + ".js");9}

In plain words, line by line:

1. Line 2 turns the button off, so more clicks do nothing while the editor loads.
2. Line 3 imports editor-panel.js, a fixed file name. The braces take the openEditor export out of the namespace object.
3. Line 4 calls openEditor with the draft section.
4. Line 8 builds the file name from a language setting.

In a project with a bundler, keep all language files in one known folder. Then the bundler can make a chunk for each one.

Common misconceptions

Here is the most common mistake. Line 2 points out the bug, and lines 3 and 4 show the fix.

1const chartPromise = import("./charts.js");2// chartPromise.render() is a bug: await the promise first.3const charts = await chartPromise;4charts.render();

Key takeaways

• import() returns a promise. The promise gives you the module namespace object, which holds the exports.
• You can build the file name in code, but bundlers work best with a fixed list or folder.
• A module runs only once. Importing the same URL again gives you the same module.
• Code splitting keeps the code for extra features out of the first download.
• Top-level await works only in modules. It makes the modules that import it wait, and no others.
• import.meta.url is the module's own URL. import.meta.resolve() turns a name into a full URL and returns a string right away.
• import defer and import source are proposals. Learn to recognize them, but don't expect every browser to run them yet.

Up next: Module resolution & import maps.