simpleStatistics = require('simple-statistics')
simpleStatistics.standardDeviation([1, 2, 3])
require's input The argument to the require function can be any of: A module name The most common case, where you simply want to include a module. For example, to require the moment date & time library:
moment = require('moment')
moment('January 2, 2018').subtract(1, 'year').year()
That module name can also include a version. You can include a semantic version specifier to allow for a range of versions, like the require statement below, which includes the newest release that matches 2.x.x.
moment2 = require('moment@2')
A module name and a path Sometimes you want to include an individual file from a module, rather than its main exported interface. This is much less common, but can be useful for modules that have addons or that don’t correctly tell unpkg which file to expose as the default. For example, here's how we can include the Chart.js module, which includes an AMD file that require can use, but doesn’t point to it by default: instead of relying on auto-detection, we specify the file directly:
Chart = require('chart.js/dist/Chart.min.js')
A URL You can also specify a full URL to require - this lets you point require at any server, not just unpkg. For example, we can load the latest version of ganja.js directly from GitHub (via RawGit).*
ganja = require('https://cdn.rawgit.com/enkimute/ganja.js/master/ganja.js')
Multiple inputs Specifying multiple inputs - multiple module names, or URLs, or module names with a path, will load all of the named things and combine their exports into one object. This is especially useful for modules like D3’s constituent modules.
// Only load the DSV and Selection parts of D3, and combine their exports into one object
d3CsvAndFetch = require("d3-dsv", "d3-selection")
require's return value require returns a promise with the module’s contents - or, if the module can’t be loaded, a promise rejection. Most of the time, you’ll use require in a cell of its own, like in the examples above, so you won’t need to worry about the return value being asynchronous. But if you do want to use require in the context of other code, you’ll need to await the value of the promise it returns.
// using await to resolve the Promise returned by require
let _ = await require('lodash');
// using the module
return _.filter([1, 2, 0]);
In some cases, too, require won’t find a module or won’t be able to load it - and it’ll return a promise rejection.
notValid = require('not-a-real-npm-module')
If you’re running into issues requiring a module, try using the module require debugger, or asking in the forum.
require’s behavior By default, the require function uses modules published on NPM, a service that hosts over 600,000 different modules* created by thousands of individual developers. Because notebooks run in a web environment, we use another service, unpkg.com, that takes NPM's modules and makes them accessible to browsers. For example, if we call require with the argument d3, it expands that argument into http://unpkg.com/d3, which then redirects to the source code of the D3 visualization library:
d3 = require('d3')
So if you see a require statement in a notebook, searching for its name on npmjs.com is likely to pull up its details - here’s the d3 package on NPM, which links to its GitHub information and other documentation. Requirements for require The require function works with modules that include AMD distributions and that point to them in the unpkg or main fields of their package.json files.* Unfortunately, not all modules are compatible: some rely on the built-in functions in Node.js that have no equivalent in the browser, and others don’t include an AMD file that require can use.
import(): a way to require ES6 modules In addition to require, which uses the widely-supported AMD standard, we also support import(), a new way of requiring modules that aims to eventually obviate the need for custom functions like require. import() is a native browser feature that’s just now gaining adoption — it only works in the newest versions of Chrome, Safari, Firefox, and Edge. It also requires modules to be published in the ES6 module specification, which is still gaining adoption. Like require, we’ve added a shortcut so that you can refer to modules by name with import() and it’ll load them from unpkg.com, if they’re available - or you can specify a full URL and it’ll pull from any other source.
scale = import('d3-scale')
require works with a subset of AMD modules that includes the vast majority of such modules: the strict specification is documented in the documentation for d3-require, the module that powers require().
More resources 🚢 Introduction to imports (like require, but for notebook-to-notebook sharing) 🤔 Require troubleshooting documentation 🐛 Module debugger tool 📦 d3-require, the module that powers require