Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

Native ES Modules in the Browser

Understand how browsers load ES modules with import and export, why bare specifiers fail, how import maps work, and how Vite uses native ESM to serve code without bundling.

Vite's speed comes from a browser feature that is older than Vite itself: native ES modules. Every modern browser can load a script with <script type="module">, follow its import statements, fetch each imported file over HTTP and run them in the right order. Vite's dev server is, at its core, a smart file server for this system. If you understand how the browser loads modules, most of Vite's behaviour stops being surprising.

Modules in one minute

A module is a file with its own scope. It shares values with other files through export and import:

JavaScript
// math.js
export const add = (a, b) => a + b;
export default function square(n) { return n * n; }
JavaScript
// main.js
import square, { add } from './math.js';
console.log(add(2, 3), square(4));

Rules that matter in the browser:

  • The import path must be a URL-like specifier: relative (./math.js, ../lib/a.js), absolute (/src/math.js) or a full URL. The file extension is required in plain browsers.
  • Modules are deferred and run in strict mode automatically.
  • Each module is fetched once, then cached by URL. Two files importing ./math.js share one instance.
  • Cycles are allowed; imports are live bindings, not copies.
  • Modules must be served over http(s) with a JavaScript MIME type. file:// fails because of CORS.
Two modules, one instance

If the sandbox blocks blob imports, the message is printed instead; the idea is the same in a real page: importing the same URL twice gives the same module instance, and n is a live binding.

The bare specifier problem

This line works in Node.js but not in a browser:

JavaScript
import { createApp } from 'vue';

'vue' is a bare specifier: not a path or URL. Node finds it by walking up to node_modules. A browser has no such folder, so it throws Failed to resolve module specifier "vue".

There are two ways to fix it without a build tool. One is an import map, a JSON block that tells the browser where each name lives:

HTML
<script type="importmap">
{
  "imports": {
    "vue": "https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.prod.js"
  }
}
</script>
<script type="module">
  import { createApp } from 'vue';
</script>

The other, which Vite chooses, is for the dev server to rewrite the specifier before sending the file. When the browser asks for /src/main.js, Vite answers with the same code, but 'vue' is replaced with /node_modules/.vite/deps/vue.js?v=abc123. Now the browser has a real URL to follow.

The waterfall question

If a page imports a module that imports five modules, each of which imports more, the browser discovers files one level at a time. This chain is called a request waterfall. For a handful of modules it is fine. For packages like lodash-es or a UI library with hundreds of internal files it would mean hundreds of requests on page load.

Vite handles this in two ways in development:

  1. Pre-bundling packages from node_modules into a few single files (see Dependency Pre-Bundling).
  2. HTTP caching: dependency files get strong cache headers (max-age=31536000,immutable) and source files use 304 Not Modified with ETags, so a reload downloads almost nothing.

For production, Vite bundles everything, because shipping hundreds of small requests to real users on slow connections is still worse than shipping a few well-split chunks.

How a request flows in development

sequenceDiagram
  participant B as Browser
  participant V as Vite dev server
  B->>V: GET /index.html
  V-->>B: HTML (script src="/src/main.js")
  B->>V: GET /src/main.js
  V-->>B: JS with imports rewritten
  B->>V: GET /src/App.vue
  V-->>B: Compiled JS (SFC transformed on request)
  B->>V: GET /node_modules/.vite/deps/vue.js
  V-->>B: Pre-bundled, long-cached

Only files the browser asks for are transformed. An unused page costs nothing.

You can see this in your browser's Network tab: each source file appears as a separate request, and .vue, .ts or .jsx files come back as plain JavaScript.

Specifier types Vite understands

A specifier in your code can mean several things; the dev server maps each to a URL:

You write Meaning Becomes
./util.js relative file /src/util.js
/src/util.js root-absolute same, relative to project root
vue npm package /node_modules/.vite/deps/vue.js?v=...
@/util alias (configured) /src/util.js
./logo.png asset a URL string for the image
./style.css stylesheet JS that injects the CSS

That last row surprises many people: in development a CSS import becomes a small JavaScript module that adds a <style> tag, which is what makes CSS updates instant.

A resolver in miniature

This stand-in shows the decision a dev server makes for each import. It is a teaching model, far simpler than Vite's real resolver.

Node.js Stand-in: classify and resolve specifiers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

What this means for you

  • Always include extensions for your own files when writing plain browser code; in Vite projects, TypeScript and Vue imports may omit them, because Vite resolves extensions (resolve.extensions), but being explicit avoids surprises.
  • Case matters. ./App.vue and ./app.vue are different URLs, even if your operating system ignores case. This causes "works on my machine" failures in deployment.
  • Side effects run once. Because modules are cached by URL, top-level code runs the first time only.
  • A syntax error in one module breaks only that module's request, and Vite shows an error overlay in the browser with the file and line.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does import { ref } from 'vue' fail in a plain browser?

    Browsers only resolve relative, absolute or full URL specifiers. Tools or import maps must map bare names to URLs.
  2. 2. How does the Vite dev server solve the bare specifier problem?

    Vite rewrites imports as it serves each file and points package imports at pre-bundled files.
  3. 3. What happens when two modules import the same URL?

    Modules are cached by URL, so top-level code runs once and the exports are shared.
  4. 4. Why does Vite still bundle for production?

    Native ESM is great for development, but production benefits from fewer requests, minification and tree shaking.

Summary

  • Native ES modules let the browser load import/export code over HTTP; each URL is fetched and evaluated once.
  • Bare specifiers (vue) are not URLs, so Vite rewrites them (or you can use an import map).
  • Vite serves, transforms and caches modules on request and pre-bundles packages to avoid huge waterfalls.
  • CSS and asset imports become JavaScript modules in development.
  • Production still uses a bundler for fewer requests and smaller output.

Next: Vite Compared With Other Build Tools