import Keyword

import Keyword

The static import declaration is used to import read-only live bindings which are exported by another module. The imported bindings are called live bindings because they are updated by the module that exported the binding, but cannot be modified by the importing module.

In order to use the import declaration in a source file, the file must be interpreted by the runtime as a module. In HTML, this is done by adding type="module" to the <script> tag. Modules are automatically interpreted in strict mode.

There is also a function-like dynamic import(), which does not require scripts of type="module".

Syntax

import defaultExport from "module-name";
import * as name from "module-name";
import { export1 } from "module-name";
import { export1 as alias1 } from "module-name";
import { default as alias } from "module-name";
import { export1, export2 } from "module-name";
import { export1, export2 as alias2, /* … */ } from "module-name";
import { "string name" as alias } from "module-name";
import defaultExport, { export1, /* … */ } from "module-name";
import defaultExport, * as name from "module-name";
import "module-name";

Name that will refer to the default export from the module. Must be a valid JavaScript identifier.

The module to import from. The evaluation of the specifier is host-specified. This is often a relative or absolute URL to the .js file containing the module. In Node, extension-less imports often refer to packages in node_modules. Certain bundlers may permit importing files without extensions; check your environment. Only single quoted and double quoted Strings are allowed.

Name of the module object that will be used as a kind of namespace when referring to the imports. Must be a valid JavaScript identifier.

Name of the exports to be imported. The name can be either an identifier or a string literal, depending on what module-name declares to export. If it is a string literal, it must be aliased to a valid identifier.

Names that will refer to the named imports. Must be a valid JavaScript identifier.

Description

import declarations can only be present in modules, and only at the top-level (i.e. not inside blocks, functions, etc.). If an import declaration is encountered in non-module contexts (for example, <script> tags without type="module", eval, new Function, which all have "script" or "function body" as parsing goals), a SyntaxError is thrown. To load modules in non-module contexts, use the dynamic import syntax instead.

import declarations are designed to be syntactically rigid (for example, only string literal specifiers, only permitted at the top-level, all bindings must be identifiers), which allows modules to be statically analyzed and linked before getting evaluated. This is the key to making modules asynchronous by nature, powering features like top-level await.

There are four forms of import declarations:

• Named import: import { export1, export2 } from "module-name";
• Default import: import defaultExport from "module-name";
• Namespace import: import * as name from "module-name";
• Side effect import: import "module-name";

Below are examples to clarify the syntax.

Named import

import { myExport } from '/modules/my-module.js';

You can import multiple names from the same module.

import { foo, bar } from '/modules/my-module.js';

You can rename an export when importing it. For example, this inserts shortName into the current scope.

import {
  reallyReallyLongModuleExportName as shortName,
} from '/modules/my-module.js';

A module may also export a member as a string literal which is not a valid identifier, in which case you must alias it in order to use it in the current module.

// /modules/my-module.js
const a = 1;
export { a as "a-b" };

import { "a-b" as a } from "/modules/my-module.js";

import myDefault from '/modules/my-module.js';

import myDefault, * as myModule from '/modules/my-module.js';
// myModule.default and myDefault point to the same binding

import myDefault, { foo, bar } from '/modules/my-module.js';

import { default as myDefault } from '/modules/my-module.js';

import * as myModule from '/modules/my-module.js';

myModule.doAllTheAmazingThings();

Import a module for its side effects only

import '/modules/my-module.js'

This is often used for polyfills, which mutate the global variables.

Examples

Standard Import

// getPrimes.js
/**
 * Returns a list of prime numbers that are smaller than `max`.
 */
function getPrimes(max) {
  const isPrime = Array.from({ length: max }, () => true);
  isPrime[0] = isPrime[1] = false;
  isPrime[2] = true;
  for (let i = 2; i * i < max; i++) {
    if (isPrime[i]) {
      for (let j = i ** 2; j < max; j += i) {
        isPrime[j] = false;
      }
    }
  }
  return [...isPrime.entries()]
    .filter(([, isPrime]) => isPrime)
    .map(([number]) => number);
}

import { getPrimes } from '/modules/getPrimes.js';

console.log(getPrimes(10)); // [2, 3, 5, 7]

Imported values can only be modified by the exporter

// my-module.js
export let myValue = 1;
setTimeout(() => {
  myValue = 2;
}, 500);

// main.js
import { myValue } from '/modules/my-module.js';
console.log(myValue); // 1
setTimeout(() => {
  console.log(myValue); // 2; my-module has updated its value
  myValue = 3; // TypeError: Assignment to constant variable.
  // The importing module can only read the value but can't re-assign it.
}, 1000);