ES6 Modules: Browser Support, Features, Known Issues

What are ES6 modules?

ES6 modules are the JavaScript module system standardized in ECMAScript 2015 and maintained by the TC39 committee. Each .js file becomes a module with its own scope, and developers use the export statement to expose values and the import statement to pull them into other files.

Which browsers support ES6 modules?

ES6 modules work natively in every major modern browser through the script type=module tag, with the exception of Internet Explorer.

What are the key features of ES6 modules?

ES6 modules add five features that change how JavaScript files load, share code, and run in a browser.

• Static import and export: The import and export keywords let one file expose specific values and another file pull them in by name. The parser reads the statements before execution, so bundlers and engines build a static dependency graph for tree-shaking and dead-code removal.
• Strict mode by default: Every module runs in JavaScript strict mode without needing the "use strict" directive. Undeclared variables, duplicate parameter names, and the with statement all throw an error instead of failing silently.
• Deferred execution: A script tag with type="module" runs after the HTML document is parsed, the same as a script with the defer attribute. The browser fetches modules in parallel and runs them in document order.
• Live bindings: When module A imports a value from module B, A reads the live binding rather than a copy. If B updates the export, A sees the new value on the next read.
• Dynamic import: The import() expression returns a Promise and lets you load a module at runtime based on user actions, route changes, or feature detection. This unlocks code splitting without a build step.

How do you use ES6 modules in a browser?

You can run ES6 modules in any modern browser by adding type="module" to the script tag and serving the files through a web server. The browser then handles fetching, parsing, and dependency resolution for you.

• Author your module: Save a .js file and use the export statement to expose functions, classes, or constants. For example, write export function add(a, b) at the top of math.js to share an add helper.
• Add type=module to the script tag: In your HTML, write <script type="module" src="main.js"></script> so the browser parses the file as a module instead of a classic script.
• Serve the file over HTTP or HTTPS: Open the page through a local web server such as npx serve or python -m http.server. Modules do not run from the file:// protocol because the browser blocks cross-origin module requests.
• Set the JavaScript MIME type: Configure your server to return text/javascript or application/javascript for .js and .mjs files. Modules served with text/plain or application/octet-stream fail to load.
• Add a nomodule fallback: Pair the module script with a transpiled fallback using <script nomodule src="legacy.js"></script>. Browsers that support modules ignore the nomodule script, and IE 11 runs only the legacy bundle.
• Confirm in DevTools: Open the Network tab in Chrome 61+, Firefox 60+, or Safari 11+, refresh the page, and check that every module file loads with a 200 status and the JavaScript MIME type.

The snippet below shows a minimal two-file ES6 module setup that runs in any modern browser through a single HTML page:

// math.js - export named values from a module
export function add(a, b) {
  return a + b;
}

export const PI = 3.14159;

// main.js - import the values into another module
import { add, PI } from './math.js';

console.log('add(2, 3):', add(2, 3));
console.log('PI is:', PI);

// In your HTML, load the entry module with type="module":
// <script type="module" src="main.js"></script>

What are the known issues with ES6 modules?

ES6 modules are widely supported, but a handful of real edge cases still trip up developers in production. The biggest hits are Internet Explorer, server configuration, and a few module-specific browser rules.

• Internet Explorer never added support: IE 11 cannot parse import or export and treats script type=module as an unknown script type. Sites that still target IE 11 must ship a transpiled ES5 bundle through the nomodule fallback.
• CORS rules apply to module scripts: Module fetches always go through CORS, even for same-origin pages opened from the file:// protocol. Pages must run on a real server, and cross-origin modules need an Access-Control-Allow-Origin header.
• Strict MIME type checks: Browsers reject module scripts that arrive with a non-JavaScript MIME type. Servers must send text/javascript or application/javascript for .js and .mjs files; text/plain or octet-stream cause the module to fail with a NetworkError.
• Bare specifiers need import maps: An import like import lodash from "lodash" does not work in the browser without an import map. Without one, every import path must start with /, ./, or ../.
• JSON, CSS, and HTML imports are still being standardized: Import attributes for JSON ship in Chrome and Edge, but CSS and HTML imports remain partial across browsers. Bundlers smooth this over, but native code may need a fetch fallback.
• Top-level await blocks the subgraph: A module that awaits at the top level pauses every module that imports it until the Promise resolves. This is useful but can stall the page if the awaited request is slow.
• Service workers and classic workers cannot import: Module scripts inside Service Workers need {type: 'module'} in the registration call, and Worker support for ES6 modules landed late in Firefox and Safari. Test worker module loading on every target browser.

In my experience, the most surprising failure happens when a developer opens an HTML file directly from the disk and sees a CORS error in the console. The page works the moment they serve the same files through npx serve, so always run modules through a real web server before debugging anything else.

Citations

All ES6 module version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - JavaScript modules: developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
• MDN Web Docs - import statement: developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
• MDN Web Docs - export statement: developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export
• TC39 - ECMAScript 2015 specification: tc39.es/ecma262/#sec-modules
• WHATWG HTML - Module scripts: html.spec.whatwg.org/multipage/webappapis.html
• Wikipedia - ECMAScript: en.wikipedia.org/wiki/ECMAScript
• Mozilla Hacks - ES modules: a cartoon deep-dive: hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive
• Chrome for Developers - New in Chrome 61: developer.chrome.com/blog/new-in-chrome-61
• WebKit - New Web Features in Safari 10.1: webkit.org/blog/7477/new-web-features-in-safari-10-1
• Microsoft Learn - Microsoft Edge release notes: learn.microsoft.com/en-us/deployedge/microsoft-edge-relnote-stable-channel
• Mozilla - Firefox 60 release notes: mozilla.org/en-US/firefox/60.0/releasenotes
• WHATWG HTML - Import maps: html.spec.whatwg.org/multipage/webappapis.html#import-maps