JarCasting
imports-loader
The imports loader allows you to use modules that depend on specific global variables.
This is useful for third-party modules that rely on global variables like $ or this being the window object. The imports loader can add the necessary require('whatever') calls, so those modules work with webpack.
For further hints on compatibility issues, check out Shimming of the official docs.
⚠ By default loader generate ES module named syntax.
⚠ Be careful, existing imports (import/require) in the original code and importing new values can cause failure.
Getting Started
To begin, you'll need to install imports-loader:
$ npm install imports-loader --save-dev
Given you have this file:
example.js
$('img').doSomeAwesomeJqueryPluginStuff();
Then you can inject the jquery value into the module by configuring the imports-loader using two approaches.
Inline
The | or %20 (space) allow to separate the syntax, moduleName, name and alias of import. The documentation and syntax examples can be read here.
⚠ %20is space in a query string, because you can't use spaces in URLs
// Alternative syntax:
//
// import myLib from 'imports-loader?imports=default%20jquery%20$!./example.js';
//
// `%20` is space in a query string, equivalently `default jquery $`
import myLib from 'imports-loader?imports=default|jquery|$!./example.js';
// Adds the following code to the beginning of example.js:
//
// import $ from "jquery";
//
// ...
// Code
// ...
import myLib from 'imports-loader?imports[]=default|jquery|$&imports[]=angular!./example.js';
// `|` is separator in a query string, equivalently `default|jquery|$` and `angular`
// Adds the following code to the beginning of example.js:
//
// import $ from "jquery";
// import angular from "angular";
//
// ...
// Code
// ...
import myLib from 'imports-loader?imports[]=named|library|myMethod&imports[]=angular!./example.js';
// `|` is separator in a query string, equivalently `named|library|myMethod` and `angular`
// Adds the following code to the beginning of example.js:
//
// import { myMethod } from "library";
// import angular from "angular";
//
// ...
// Code
// ...
const myLib = require(`imports-loader?type=commonjs&imports[]=single|jquery|$&imports[]=angular!./example.js`);
// `|` is separator in a query string, equivalently `single|jquery|$` and `angular`
// Adds the following code to the beginning of example.js:
//
// var $ = require("jquery");
// var angular = require("angular");
//
// ...
// Code
// ...
const myLib = require(`imports-loader?type=commonjs&imports=single|myLib|myMethod&wrapper=window&!./example.js`);
// `|` is separator in a query string, equivalently `single|myLib|myMethod` and `angular`
// Adds the following code to the example.js:
//
// const myMethod = require('myLib');
//
// (function () {
// ...
// Code
// ...
// }.call(window));
import myLib from 'imports-loader?additionalCode=var%20myVariable%20=%20false;!./example.js';
// Adds the following code to the beginning of example.js:
//
// var myVariable = false;
//
// ...
// Code
// ...
Using Configuration
webpack.config.js
module.exports = {
module: {
rules: [
{
// You can use `regexp`
// test: /example\.js/$
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: [
'default jquery $',
'default lib_2 lib_2_default',
'named lib_3 lib2_method_1',
'named lib_3 lib2_method_2 lib_2_method_2_short',
'namespace lib_4 my_namespace',
'side-effects lib_5',
{
syntax: 'default',
moduleName: 'angular',
name: 'angular',
},
],
},
},
],
},
],
},
};
Generate output:
import $ from 'jquery';
import lib_2_default from 'lib_2';
import { lib2_method_1, lib2_method_2 as lib_2_method_2_short } from 'lib_3';
import * as my_namespace from 'lib_4';
import 'lib_5';
import angular from 'angular';
And run webpack via your preferred method.
Options
| Name | Type | Default | Description |
|---|---|---|---|
type |
{String} |
module |
Format of generated imports |
imports |
{String|Object|Array<String|Object>} |
undefined |
List of imports |
wrapper |
{Boolean|String|Object} |
undefined |
Closes the module code in a function ((function () { ... }).call();) |
additionalCode |
{String} |
undefined |
Adds custom code |
type
Type: String Default: module
Format of generated exports.
Possible values - commonjs (CommonJS module syntax) and module (ES module syntax).
commonjs
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
loader: 'imports-loader',
options: {
syntax: 'default',
type: 'commonjs',
imports: 'Foo',
},
},
],
},
};
Generate output:
var Foo = require('Foo');
// ...
// Code
// ...
module
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
loader: 'imports-loader',
options: {
type: 'module',
imports: 'Foo',
},
},
],
},
};
Generate output:
import Foo from 'Foo';
// ...
// Code
// ...
imports
Type: String|Object|Array<String|Object> Default: undefined
List of imports.
String
Allows to use a string to describe an export.
Syntax
The | or %20 (space) allow to separate the syntax, moduleName, name and alias of import.
String syntax - [[syntax] [moduleName] [name] [alias]] or [[syntax]|[moduleName]|[name]|[alias]], where:
-
[syntax](may be omitted):- if
typeismodule- can bedefault,named,namespaceorside-effects, the default value isdefault. - if
typeiscommonjs- can besingle,multipleorpure, the default value issingle.
- if
-
[moduleName]- name of an imported module (required) -
[name]- name of an imported value (required) -
[alias]- alias of an imported value (may be omitted)
Examples:
If type module:
[Foo]- generatesimport Foo from "Foo";.[default Foo]- generatesimport Foo from "Foo";.[default ./my-lib Foo]- generatesimport Foo from "./my-lib";.[named Foo FooA]- generatesimport { FooA } from "Foo";.[named Foo FooA Bar]- generatesimport { FooA as Bar } from "Foo";.[namespace Foo FooA]- generatesimport * as FooA from "Foo";.[side-effects Foo]- generatesimport "Foo";.
If type commonjs:
[Foo]- generatesconst Foo = require("Foo");.[single Foo]- generatesconst Foo = require("Foo");.[single ./my-lib Foo]- generatesconst Foo = require("./my-lib");.[multiple Foo FooA Bar]- generatesconst { FooA: Bar } = require("Foo");.[pure Foo]- generatesrequire("Foo");.
⚠ You need to settype: "commonjs"to usesingle,multipleandpuresyntaxes.
⚠ Aliases can't be used together withdefault,namespace,side-effects,singleandpuresyntaxes.
Examples
ES Module Default Import
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('./path/to/example.js'),
loader: 'imports-loader',
options: {
imports: 'default lib myName',
},
},
],
},
};
Generate output:
import myName from 'lib';
// ...
// Code
// ...
CommonJS Single Import
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('./path/to/example.js'),
loader: 'imports-loader',
options: {
type: 'commonjs',
exports: 'single lib myName',
},
},
],
},
};
Generate output:
var myName = require('lib');
// ...
// Code
// ...
Object
Allows to use an object to describe an import.
Properties:
-
syntax:- if
typeismodule- can bedefault,named,namespaceorside-effects - if
typeiscommonjs- can besingle,multipleorpure
- if
-
moduleName- name of an imported module (required) -
name- name of an imported value (required) -
alias- alias of an imported value (may be omitted)
⚠ Alias can't be used together withdefault,namespace,side-effects,singleandpuresyntaxes.
Examples
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: {
syntax: 'named',
moduleName: 'lib_2',
name: 'lib2_method_2',
alias: 'lib_2_method_2_alias',
},
},
},
],
},
],
},
};
Generate output:
import { lib2_method_2 as lib_2_method_2_alias } from 'lib_2';
// ...
// Code
// ...
Array
Allow to specify multiple imports. Each item can be a string or an object.
Examples
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: [
{
moduleName: 'angular',
},
{
syntax: 'default',
moduleName: 'jquery',
name: '$',
},
'default lib_2 lib_2_default',
'named lib_2 lib2_method_1',
'named lib_2 lib2_method_2 lib_2_method_2_alias',
'namespace lib_3 lib_3_all',
'side-effects lib_4',
],
},
},
],
},
],
},
};
Generate output:
import angular from 'angular';
import $ from 'jquery';
import lib_2_default from 'lib_2';
import { lib2_method_1, lib2_method_2 as lib_2_method_2_alias } from 'lib_2';
import * as lib_3_all from 'lib_3';
import 'lib_4';
// ...
// Code
// ...
wrapper
Type: Boolean|String|Object Default: undefined
Closes the module code in a function with a given thisArg and args ((function () { ... }).call();).
⚠ Do not use this option if source code contains ES module import(s)
Boolean
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: {
moduleName: 'jquery',
name: '$',
},
wrapper: true,
},
},
],
},
],
},
};
Generate output:
import $ from 'jquery';
(function () {
// ...
// Code
// ...
}.call());
String
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: {
moduleName: 'jquery',
name: '$',
},
wrapper: 'window',
},
},
],
},
],
},
};
Generate output:
import $ from 'jquery';
(function () {
// ...
// Code
// ...
}.call(window));
Object
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: {
moduleName: 'jquery',
name: '$',
},
wrapper: {
thisArg: 'window',
args: ['myVariable', 'myOtherVariable'],
},
},
},
],
},
],
},
};
Generate output:
import $ from 'jquery';
(function (myVariable, myOtherVariable) {
// ...
// Code
// ...
}.call(window, myVariable, myOtherVariable));
Object with different parameter names
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: {
moduleName: 'jquery',
name: '$',
},
wrapper: {
thisArg: 'window',
args: {
myVariable: 'var1',
myOtherVariable: 'var2',
},
},
},
},
],
},
],
},
};
Generate output:
import $ from 'jquery';
(function (var1, var2) {
// ...
// Code
// ...
}.call(window, myVariable, myOtherVariable));
additionalCode
Type: String Default: undefined
Adds custom code as a preamble before the module's code.
Examples
Define custom variable
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: {
moduleName: 'jquery',
name: '$',
},
additionalCode: 'var myVariable = false;',
},
},
],
},
],
},
};
Generate output:
import $ from 'jquery';
var myVariable = false;
// ...
// Code
// ...
Disable AMD Import Syntax
webpack.config.js
module.exports = {
module: {
rules: [
{
test: require.resolve('example.js'),
use: [
{
loader: 'imports-loader',
options: {
imports: {
moduleName: 'jquery',
name: '$',
},
additionalCode:
'var define = false; /* Disable AMD for misbehaving libraries */',
},
},
],
},
],
},
};
Generate output:
import $ from 'jquery';
var define = false; /* Disable AMD for misbehaving libraries */
// ...
// Code
// ...
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
