webpack-contrib/imports-loader webpack-contrib/imports-loader

  • Stars
    star
    520
  • Rank 81,753 (Top 2 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 11 years ago
  • Updated about 2 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
webpack-contrib/imports-loader
github

webpack-contrib

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Imports Loader

npm node tests cover discussion size

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.

Warning

By default loader generate 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

or

yarn add -D imports-loader

or

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 is 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 $ 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

type

Type:

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:

type imports =
  | string
  | {
      syntax:
        | "default"
        | "named"
        | "namespace"
        | "side-effects"
        | "single"
        | "multiple"
        | "pure";
      moduleName: string;
      name: string;
      alias: string;
    }
  | Array<
      | 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:

var 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 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> | Array<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)

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:

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

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.

CONTRIBUTING

License

MIT

More Repositories

1

webpack-bundle-analyzer

Webpack plugin and CLI utility that represents bundle content as convenient interactive zoomable treemap
JavaScript
12,483
star
2

mini-css-extract-plugin

Lightweight CSS extraction plugin
JavaScript
4,621
star
3

awesome-webpack

A curated list of awesome Webpack resources, libraries and tools
HTML
4,566
star
4

css-loader

CSS Loader
JavaScript
4,274
star
5

extract-text-webpack-plugin

[DEPRECATED] Please use https://github.com/webpack-contrib/mini-css-extract-plugin Extracts text from a bundle into a separate file
JavaScript
4,020
star
6

sass-loader

Compiles Sass to CSS
JavaScript
3,890
star
7

postcss-loader

PostCSS loader for webpack
JavaScript
2,845
star
8

copy-webpack-plugin

Copy files and directories with webpack
JavaScript
2,820
star
9

webpack-hot-middleware

Webpack hot reloading you can attach to your own server
JavaScript
2,335
star
10

terser-webpack-plugin

Terser Plugin
JavaScript
1,924
star
11

file-loader

File Loader
JavaScript
1,866
star
12

style-loader

Style Loader
JavaScript
1,642
star
13

worker-loader

A webpack loader that registers a script as a Web Worker
JavaScript
1,448
star
14

install-webpack-plugin

Speed up development by automatically installing & saving dependencies with Webpack.
JavaScript
1,434
star
15

url-loader

A loader for webpack which transforms files into base64 URIs
JavaScript
1,407
star
16

compression-webpack-plugin

Prepare compressed versions of assets to serve them with Content-Encoding
JavaScript
1,400
star
17

uglifyjs-webpack-plugin

[deprecated] UglifyJS Plugin
JavaScript
1,382
star
18

html-loader

HTML Loader
JavaScript
1,161
star
19

thread-loader

Runs the following loaders in a worker pool
JavaScript
1,114
star
20

webpack-serve

Repository has moved:
JavaScript
1,094
star
21

eslint-loader

[DEPRECATED] A ESlint loader for webpack
JavaScript
1,057
star
22

less-loader

Compiles Less to CSS
JavaScript
952
star
23

raw-loader

A loader for webpack that allows importing files as a String
JavaScript
846
star
24

purifycss-webpack

UNMAINTAINED, use https://github.com/FullHuman/purgecss-webpack-plugin
JavaScript
773
star
25

bundle-loader

Bundle Loader
JavaScript
662
star
26

cache-loader

[DEPRECATED] Caches the result of following loaders on disk
JavaScript
640
star
27

expose-loader

Expose Loader
JavaScript
545
star
28

stylus-loader

🎨 A stylus loader for webpack.
JavaScript
498
star
29

babel-minify-webpack-plugin

[DEPRECATED] Babel Minify Webpack Plugin
JavaScript
493
star
30

svg-inline-loader

Inline SVG loader with cleaning-up functionality
JavaScript
490
star
31

json-loader

json loader module for webpack - UNMAINTAINED
JavaScript
438
star
32

closure-webpack-plugin

Webpack Google Closure Compiler and Closure Library plugin -
JavaScript
434
star
33

stylelint-webpack-plugin

A Stylelint plugin for webpack
JavaScript
425
star
34

source-map-loader

extract sourceMappingURL comments from modules and offer it to webpack
JavaScript
355
star
35

script-loader

[deprecated] Script Loader
JavaScript
325
star
36

i18n-webpack-plugin

[DEPRECATED] Embed localization into your bundle
JavaScript
318
star
37

css-minimizer-webpack-plugin

cssnano plugin for Webpack
JavaScript
305
star
38

istanbul-instrumenter-loader

Istanbul Instrumenter Loader
JavaScript
273
star
39

grunt-webpack

integrate webpack into grunt build process
JavaScript
266
star
40

react-proxy-loader

Wraps a react component in a proxy component to enable Code Splitting.
JavaScript
259
star
41

eslint-webpack-plugin

A ESLint plugin for webpack
JavaScript
250
star
42

image-minimizer-webpack-plugin

Webpack loader and plugin to compress images using imagemin
JavaScript
220
star
43

exports-loader

Exports Loader
JavaScript
214
star
44

webpack-command

[DEPRECATED] Lightweight, modular, and opinionated webpack CLI that provides a superior experience
JavaScript
213
star
45

webpack-stylish

A stylish, optionated reporter for webpack
JavaScript
202
star
46

val-loader

val loader module for webpack
JavaScript
181
star
47

mocha-loader

Mocha Loader
JavaScript
147
star
48

null-loader

[DEPRECATED] A loader that returns an empty module (can still be used for webpack 4).
JavaScript
144
star
49

coffee-loader

CoffeeScript Loader
JavaScript
142
star
50

webpack-hot-client

webpack HMR Client
JavaScript
121
star
51

node-loader

node loader for native modules
JavaScript
116
star
52

transform-loader

transform loader for webpack
JavaScript
110
star
53

webpack-defaults

Defaults to be shared across webpack projects
JavaScript
108
star
54

json5-loader

[Deprecated] JSON5 loader for Webpack (can still be used for webpack 4)
JavaScript
72
star
55

jshint-loader

[DEPRECATED] jshint loader for webpack, please migrate on `eslint`
JavaScript
67
star
56

webpack-canary

Canary tooling for checking webpack dependencies against specific webpack versions
JavaScript
47
star
57

multi-loader

[DEPRECATED] A loader that splits a module into multiple modules loaded with different loaders.
JavaScript
44
star
58

webpack-log

[DEPRECATED] Please use logger API https://github.com/webpack/webpack/pull/9436
JavaScript
38
star
59

zopfli-webpack-plugin

[DEPRECATED] Prepare compressed versions of assets with node-zopfli
JavaScript
26
star
60

component-webpack-plugin

Use components with webpack - UNMAINTAINED
JavaScript
20
star
61

remark-loader

Load markdown through remark with image resolving and some react-specific features.
JavaScript
15
star
62

gzip-loader

[DEPRECATED] gzip loader module for webpack
JavaScript
15
star
63

yaml-frontmatter-loader

[DEPRECATED] Yaml frontmatter loader
JavaScript
14
star
64

json-minimizer-webpack-plugin

JSON minimizer webpack plugin
JavaScript
14
star
65

config-loader

[DEPRECATED] A loader for webpack configuration files
JavaScript
14
star
66

html-minimizer-webpack-plugin

HTML minimizer webpack plugin
JavaScript
13
star
67

organization

Applications, Standards & Documentation for webpack-contrib.
13
star
68

i18n-loader

i18n loader module for webpack - UNMAINTAINED
JavaScript
11
star
69

eslint-config-webpack

Webpack standard eslint configuration
JavaScript
9
star
70

coffee-redux-loader

coffee redux loader module for webpack - UNMAINTAINED
JavaScript
7
star
71

test-utils

webpack Loader/Plugin Test Helpers
JavaScript
6
star
72

coverjs-loader

coverjs loader module for webpack - UNMAINTAINED
JavaScript
4
star
73

circleci-node8

[DEPRECATED] Please migrate on azure pipelines. CircleCI 2.0 NodeJS 8 build container -
Dockerfile
3
star
74

restyle-loader

[DEPRECATED] Use https://github.com/danielverejan/restyle-loader
JavaScript
3
star
75

tag-versions

A commandline wrapper around omichelsen/compare-versions to compare dist-tags
JavaScript
2
star
76

circleci-node-base

CircleCI 2.0 base build container -
Dockerfile
1
star
77

babel-preset-webpack

[DEPRECATED] Webpack Organization es2015 Babel Preset - See:
JavaScript
1
star
78

circleci-node9

[DEPRECATED] Please migrate on azure pipelines. CircleCI 2.0 NodeJS 9 build container -
Dockerfile
1
star
79

circleci-node-jdk8

Deprecated, use ->
1
star
80

cli-utils

[DEPRECATED] A suite of utilities for webpack projects which expose a CLI
JavaScript
1
star