imports-loader

Disclaimer: imports-loader is a third-party package maintained by community members, it potentially does not have the same support, security policy or license as webpack, and it is not maintained by webpack.

The imports loader allows you to use modules that depend on specific global variables.

This is especially useful for third-party modules that rely on global variables like $ or where this is expected to be 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, see the official webpack documentation on Shimming.

[!WARNING]

By default, this loader generates ES module named syntax.

[!WARNING]

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

yarn add -D imports-loader

pnpm add -D imports-loader

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.

[!WARNING]

%20 represents a 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|$,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,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|$,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 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_short } from "lib_3";
import * as my_namespace from "lib_4";
import "lib_5";

Finally, run webpack using the method you normally use (e.g., via CLI or an npm script).

Options

type
imports
wrapper
additionalCode

`type`

Type:

type type = string;

Default: module

Defines the format of generated exports.

Possible values:

commonjs (CommonJS module syntax)
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:

const 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:

type imports =
  | string
  | {
      syntax:
        | "default"
        | "named"
        | "namespace"
        | "side-effects"
        | "single"
        | "multiple"
        | "pure";
      moduleName: string;
      name: string;
      alias: string;
    }
  | (
      | string
      | {
          syntax:
            | "default"
            | "named"
            | "namespace"
            | "side-effects"
            | "single"
            | "multiple"
            | "pure";
          moduleName: string;
          name: string;
          alias: string;
        }
    )[];

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 type is module- can be default, named, namespace or side-effects, the default value is default.
- if type is commonjs- can be single, multiple or pure, the default value is single.
[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] - generates import Foo from "Foo";.
[default Foo] - generates import Foo from "Foo";.
[default ./my-lib Foo] - generates import Foo from "./my-lib";.
[named Foo FooA] - generates import { FooA } from "Foo";.
[named Foo FooA Bar] - generates import { FooA as Bar } from "Foo";.
[namespace Foo FooA] - generates import * as FooA from "Foo";.
[side-effects Foo] - generates import "Foo";.

If type commonjs:

[Foo] - generates const Foo = require("Foo");.
[single Foo] - generates const Foo = require("Foo");.
[single ./my-lib Foo] - generates const Foo = require("./my-lib");.
[multiple Foo FooA Bar] - generates const { FooA: Bar } = require("Foo");.
[pure Foo] - generates require("Foo");.

[!WARNING]

You need to set type: "commonjs" to use single, multiple and pure syntaxes.

[!WARNING]

Aliases can't be used together with default, namespace, side-effects, single and pure syntaxes.

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",
          imports: "single lib myName",
        },
      },
    ],
  },
};

Generate output:

const myName = require("lib");

// ...
// Code
// ...

`object`

Allows to use an object to describe an import.

Properties:

syntax:
- if type is module- can be default, named, namespace or side-effects
- if type is commonjs- can be single, multiple or pure
moduleName - name of an imported module (required)
name - name of an imported value (required)
alias - alias of an imported value (may be omitted)

[!WARNING]

Alias can't be used together with default, namespace, side-effects, single and pure syntaxes.

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 either 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:

type wrapper =
  | boolean
  | string
  | {
      thisArg: string;
      args: Record<string, string> | string[];
    };

Default: undefined

Closes the module code in a function with a given thisArg and args ((function () { ... }).call();).

[!WARNING]

Do not use this option if source code contains ES module import(s). It is intended for legacy or non-ESM compatible code.

`boolean`

Wraps the code in an IIFE (Immediately Invoked Function Expression) with default context.

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`

Passes a custom thisArg to the .call() context.

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(globalThis);

`object`

Allows advanced control: specify the this context and custom arguments passed into the IIFE

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(globalThis, myVariable, myOtherVariable);

`object` with different parameter names

Allows remapping argument names in the function signature using a key-value 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: "var1",
                  myOtherVariable: "var2",
                },
              },
            },
          },
        ],
      },
    ],
  },
};

Generate output:

import $ from "jquery";

(function (var1, var2) {
  // ...
  // Code
  // ...
}).call(globalThis, myVariable, myOtherVariable);

`additionalCode`

Type:

type additionalCode = 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";

const 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";

const define = false; /* Disable AMD for misbehaving libraries */

// ...
// Code
// ...

Contributing

We welcome contributions! If you’re interested in helping improve this loader, please take a moment to read our contributing guidelines.

CONTRIBUTING

License

MIT

Edit this page·Print this page·Jump to repository

« Previous

html-loader

remark-loader

imports-loader

Getting Started

Inline

Using Configuration

Options

type

commonjs

module

imports

string

Syntax

Examples

ES Module Default Import

CommonJS Single Import

object

Examples

array

Examples

wrapper

boolean

string

object

object with different parameter names

additionalCode

Examples

Define custom variable

Disable AMD Import Syntax

Contributing

License

`type`

`commonjs`

`module`

`imports`

`string`

`Syntax`

`object`

`array`

`wrapper`

`boolean`

`string`

`object`

`object` with different parameter names

`additionalCode`