liveBook · Manning

Import statement

As explained in Get Programming with JavaScript Next: New features of ECMAScript 2015, 2016, and beyond

A JavaScript module syntax form that brings bindings or module code into the current module from another module.

Need functions from another file without putting them in global variables? An import statement brings exported values into the current JavaScript module. It answers two questions: what do you want, and where is it? In `import formatCurrency from './utils/format/currency'`, `formatCurrency` is the local name and the string is the module location. The location must be a string literal, not a variable: imports are identified before the current file runs. section 21.0 section 21.1 section 21.2

Choose the form that matches what the module exports:

  • Default: `import formatCurrency from './utils/format/currency'`. A default export supplies one value; you choose its local name. section 21.2
  • Named: `import { currency, number } from './utils/format'`. These names must match the exports. Rename locally with `import { number as formatter } from './utils/format'`—handy when two modules export the same name. section 21.2
  • Namespace: `import * as format from './utils/format'`, then call `format.currency(1)`. You can also combine a default import with named or namespace imports. section 21.2

The meaning of a location string depends on the loader. In the Browserify and Webpack examples, `./file` and `./file.js` refer to a file relative to the importing file; omitting the extension can also allow a directory’s `index.js` to match. Do not treat those resolution details as a rule for every JavaScript environment. section 21.1

An imported name that changes

Suppose `./title_master` exports `let title = 'Java'` and a `setTitle(newTitle)` function that assigns to `title`. After `import { title, setTitle } from './title_master'`, logging `title`, calling `setTitle('Script')`, and logging again produces `Java`, then `Script`. You cannot assign to the imported `title` yourself: imports are read-only in the importing module. But this named import stays bound to the exported variable, so a change made by its module appears wherever it is imported, without a notification. section 21.3

If you need a module to run but need none of its values, use a side-effect import: `import './google_analytics'`. Its code executes before code in the importing file, even if the import appears later. Quick check: with `console.log('A')`, then `import './log_b'`, then `console.log('C')`, what prints first if `log_b` prints `B`? The order is `B`, `A`, `C`. section 21.4

How Get Programming with JavaScript Next: New features of ECMAScript 2015, 2016, and beyond covers it

How deep it goes
Works through location syntax, import forms, bindings, and execution order; leaves environment-specific module resolution to loaders.
Examples
Uses currency formatting, a changing title, analytics setup, and a logging-order check to distinguish import behaviors.
What it assumes
Assumes familiarity with modules and exports, while explaining import forms and their behavior through short examples.
What you can do after
Practice/perform it by choosing default, named, namespace, or side-effect imports and predicting when imported code runs.
How it connects
Connects default exports, named exports, namespace imports, live bindings, module loaders, and side effects.

Also explained in

Compare how 13 books explain import statement →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Get Programming with JavaScript Next: New features of ECMAScript 2015, 2016, and beyond. The section links point to the parts of the book it draws on.