imports-loader

5.0.0 verified Sat Apr 25 auth: no javascript

A webpack loader that automatically injects import/require statements for global variables into modules, enabling third-party code that depends on globals like $ or this to work with webpack's module system. Current stable version is 5.0.0 (January 2024), released under the webpack-contrib organization. It supports inline query syntax and webpack config rules, offering fine-grained control over import type (ESM, CommonJS), variable names, and module aliases. Key differentiators: explicit control over shimming via loader query parameters, support for named and default imports, and ability to wrap code in an IIFE with custom arguments. Requires webpack 5 and Node 18.12+. Releases follow semver with major bumps for Node and webpack version requirements.

Common errors

error Module parse failed: The keyword 'import' is reserved ↓

cause Loader generates ESM imports but webpack configuration expects CommonJS or target doesn't support ES modules.

fix

Set options.type to 'commonjs' in loader config, or ensure webpack is configured for ES modules.

error SyntaxError: Unexpected token '|' ↓

cause Using pipe character '|' incorrectly in Inline loader query string, or forgetting to escape spaces.

fix

Ensure inline syntax follows pattern: imports-loader?imports=syntax|module|name,nextSyntax|module|name!./file.js

error Error: Cannot find module 'imports-loader' ↓

cause imports-loader not installed or missing in devDependencies.

fix

Run npm install imports-loader --save-dev

Warnings

breaking Minimum supported Node.js version is 18.12.0 ↓

fix Upgrade Node.js to 18.12.0 or higher.

breaking Minimum supported webpack version is 5 ↓

fix Use webpack 5. If using webpack 4, use imports-loader v1.

breaking Inline syntax changed: [] is no longer supported for multiple imports; use comma separator ↓

fix Replace `imports[]=default|jquery|$&imports[]=angular` with `imports=default|jquery|$,angular`.

gotcha Existing import/require statements in the original code may conflict with injected imports ↓

fix Ensure injected imports do not duplicate existing imports. Consider using 'additionalCode' or 'wrapper' to handle conflicts.

gotcha By default, loader generates ES module named syntax (import). For CommonJS, set type: 'commonjs' ↓

fix Use `type: 'commonjs'` in options if your target module uses CommonJS require.

Install

npm install imports-loader

yarn add imports-loader

pnpm add imports-loader

Imports

default (loader in webpack config or inline)

wrong

Using require('imports-loader') directly in code instead of webpack config

correct

module.exports = { module: { rules: [ { test: /example\.js$/, use: [{ loader: 'imports-loader', options: { imports: ['default jquery $'] } }] } ] } }

Loader is used in webpack configuration or inline import syntax, not imported directly in application code.

imports-loader with type commonjs and wrapper
wrong
```
Using older inline syntax with [] brackets (e.g., imports[]=default|jquery|$&imports[]=angular)
```
correct
```
const myLib = require(`imports-loader?type=commonjs&imports=single|jquery|$&wrapper=window!./example.js`);
```
Inline syntax changed in v2.0.0: use comma separation instead of multiple [] parameters. The `|` delimiter is used between syntax, moduleName, name, and alias.

named import via loader

wrong

Using default import syntax for named exports (e.g., imports=default|library|myMethod) would try to import default instead of named export.

correct

import myLib from 'imports-loader?imports=named|library|myMethod,angular!./example.js';

Use 'named' syntax for named exports from a module, 'default' for default exports, 'single' for entire module as a variable.

additionalCode option

wrong

Using newline characters or unescaped spaces in inline query string

correct

import myLib from 'imports-loader?additionalCode=var%20myVariable%20=%20false;!./example.js';

Spaces must be encoded as %20 in inline syntax. Alternatively, use webpack config options object for readability.

Quickstart

Shows webpack config using imports-loader to inject jquery, angular, and lodash/map into a module, demonstrating default and named imports.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: require.resolve('example.js'),
        use: [
          {
            loader: 'imports-loader',
            options: {
              imports: [
                'default jquery $',
                'default angular angular',
                'named lodash map'
              ],
              type: 'module' // default is ESM
            }
          }
        ]
      }
    ]
  }
};
// example.js
// Original code using global $:
$('button').click(function() { console.log('clicked'); });
// After loader processes, the file effectively starts with:
// import $ from 'jquery';
// import angular from 'angular';
// import { map } from 'lodash';