{"id":13527898,"url":"https://github.com/webpack-contrib/imports-loader","last_synced_at":"2025-04-29T14:20:59.360Z","repository":{"id":5376595,"uuid":"6563905","full_name":"webpack-contrib/imports-loader","owner":"webpack-contrib","description":"Imports Loader","archived":false,"fork":false,"pushed_at":"2025-01-21T17:27:59.000Z","size":3097,"stargazers_count":520,"open_issues_count":0,"forks_count":63,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-28T00:16:47.949Z","etag":null,"topics":["webpack-loader"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webpack-contrib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"webpack"}},"created_at":"2012-11-06T15:03:17.000Z","updated_at":"2025-04-14T03:46:42.000Z","dependencies_parsed_at":"2023-12-03T07:25:25.938Z","dependency_job_id":"4dd4466b-94cd-4421-97e6-a04a15d57f2e","html_url":"https://github.com/webpack-contrib/imports-loader","commit_stats":{"total_commits":131,"total_committers":37,"mean_commits":"3.5405405405405403","dds":0.6870229007633588,"last_synced_commit":"60e7bcc43e15465d65a6fcef401466faca2bf3b8"},"previous_names":["webpack/imports-loader"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fimports-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fimports-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fimports-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fimports-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webpack-contrib","download_url":"https://codeload.github.com/webpack-contrib/imports-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251225464,"owners_count":21555282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["webpack-loader"],"created_at":"2024-08-01T06:02:05.844Z","updated_at":"2025-04-29T14:20:59.336Z","avatar_url":"https://github.com/webpack-contrib.png","language":"JavaScript","funding_links":["https://opencollective.com/webpack"],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/webpack/webpack\"\u003e\n    \u003cimg width=\"200\" height=\"200\"\n      src=\"https://webpack.js.org/assets/icon-square-big.svg\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n[![npm][npm]][npm-url]\n[![node][node]][node-url]\n[![tests][tests]][tests-url]\n[![cover][cover]][cover-url]\n[![discussion][discussion]][discussion-url]\n[![size][size]][size-url]\n\n# imports-loader\n\nThe imports loader allows you to use modules that depend on specific global variables.\n\nThis is useful for third-party modules that rely on global variables like `$` or `this` being the `window` object.\nThe imports loader can add the necessary `require('whatever')` calls, so those modules work with webpack.\n\nFor further hints on compatibility issues, check out [Shimming](https://webpack.js.org/guides/shimming/) of the official docs.\n\n\u003e [!WARNING]\n\u003e\n\u003e By default loader generate ES module named syntax.\n\n\u003e [!WARNING]\n\u003e\n\u003e Be careful, existing imports (`import`/`require`) in the original code and importing new values can cause failure.\n\n## Getting Started\n\nTo begin, you'll need to install `imports-loader`:\n\n```console\nnpm install imports-loader --save-dev\n```\n\nor\n\n```console\nyarn add -D imports-loader\n```\n\nor\n\n```console\npnpm add -D imports-loader\n```\n\nGiven you have this file:\n\n**example.js**\n\n```js\n$(\"img\").doSomeAwesomeJqueryPluginStuff();\n```\n\nThen you can inject the `jquery` value into the module by configuring the `imports-loader` using two approaches.\n\n### Inline\n\nThe `|` or `%20` (space) allow to separate the `syntax`, `moduleName`, `name` and `alias` of import.\nThe documentation and syntax examples can be read [here](#syntax).\n\n\u003e [!WARNING]\n\u003e\n\u003e `%20` is space in a query string, because you can't use spaces in URLs\n\n```js\n// Alternative syntax:\n//\n// import myLib from 'imports-loader?imports=default%20jquery%20$!./example.js';\n//\n// `%20` is space in a query string, equivalently `default jquery $`\nimport myLib from \"imports-loader?imports=default|jquery|$!./example.js\";\n// Adds the following code to the beginning of example.js:\n//\n// import $ from \"jquery\";\n//\n// ...\n// Code\n// ...\n```\n\n```js\nimport myLib from \"imports-loader?imports=default|jquery|$,angular!./example.js\";\n// `|` is separator in a query string, equivalently `default|jquery|$` and `angular`\n// Adds the following code to the beginning of example.js:\n//\n// import $ from \"jquery\";\n// import angular from \"angular\";\n//\n// ...\n// Code\n// ...\n```\n\n```js\nimport myLib from \"imports-loader?imports=named|library|myMethod,angular!./example.js\";\n// `|` is separator in a query string, equivalently `named|library|myMethod` and `angular`\n// Adds the following code to the beginning of example.js:\n//\n// import { myMethod } from \"library\";\n// import angular from \"angular\";\n//\n// ...\n// Code\n// ...\n```\n\n```js\nconst myLib = require(\n  `imports-loader?type=commonjs\u0026imports=single|jquery|$,angular!./example.js`,\n);\n// `|` is separator in a query string, equivalently `single|jquery|$` and `angular`\n// Adds the following code to the beginning of example.js:\n//\n// var $ = require(\"jquery\");\n// var angular = require(\"angular\");\n//\n// ...\n// Code\n// ...\n```\n\n```js\nconst myLib = require(\n  `imports-loader?type=commonjs\u0026imports=single|myLib|myMethod\u0026wrapper=window\u0026!./example.js`,\n);\n// `|` is separator in a query string, equivalently `single|myLib|myMethod` and `angular`\n// Adds the following code to the example.js:\n//\n// const myMethod = require('myLib');\n//\n// (function () {\n// ...\n// Code\n// ...\n// }.call(window));\n```\n\n```js\nimport myLib from \"imports-loader?additionalCode=var%20myVariable%20=%20false;!./example.js\";\n// Adds the following code to the beginning of example.js:\n//\n// var myVariable = false;\n//\n// ...\n// Code\n// ...\n```\n\n### Using Configuration\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        // You can use `regexp`\n        // test: /example\\.js$/\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: [\n                \"default jquery $\",\n                \"default lib_2 lib_2_default\",\n                \"named lib_3 lib2_method_1\",\n                \"named lib_3 lib2_method_2 lib_2_method_2_short\",\n                \"namespace lib_4 my_namespace\",\n                \"side-effects lib_5\",\n                {\n                  syntax: \"default\",\n                  moduleName: \"angular\",\n                  name: \"angular\",\n                },\n              ],\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport $ from \"jquery\";\nimport lib_2_default from \"lib_2\";\nimport { lib2_method_1, lib2_method_2 as lib_2_method_2_short } from \"lib_3\";\nimport * as my_namespace from \"lib_4\";\nimport \"lib_5\";\nimport angular from \"angular\";\n```\n\nAnd run `webpack` via your preferred method.\n\n## Options\n\n- **[`type`](#type)**\n- **[`imports`](#imports)**\n- **[`wrapper`](#wrapper)**\n- **[`additionalCode`](#additionalcode)**\n\n### `type`\n\nType:\n\n```ts\ntype type = string;\n```\n\nDefault: `module`\n\nFormat of generated exports.\n\nPossible values - `commonjs` (CommonJS module syntax) and `module` (ES module syntax).\n\n#### `commonjs`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        loader: \"imports-loader\",\n        options: {\n          syntax: \"default\",\n          type: \"commonjs\",\n          imports: \"Foo\",\n        },\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nvar Foo = require(\"Foo\");\n\n// ...\n// Code\n// ...\n```\n\n#### `module`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        loader: \"imports-loader\",\n        options: {\n          type: \"module\",\n          imports: \"Foo\",\n        },\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport Foo from \"Foo\";\n\n// ...\n// Code\n// ...\n```\n\n### `imports`\n\nType:\n\n```ts\ntype imports =\n  | string\n  | {\n      syntax:\n        | \"default\"\n        | \"named\"\n        | \"namespace\"\n        | \"side-effects\"\n        | \"single\"\n        | \"multiple\"\n        | \"pure\";\n      moduleName: string;\n      name: string;\n      alias: string;\n    }\n  | Array\u003c\n      | string\n      | {\n          syntax:\n            | \"default\"\n            | \"named\"\n            | \"namespace\"\n            | \"side-effects\"\n            | \"single\"\n            | \"multiple\"\n            | \"pure\";\n          moduleName: string;\n          name: string;\n          alias: string;\n        }\n    \u003e;\n```\n\nDefault: `undefined`\n\nList of imports.\n\n#### `string`\n\nAllows to use a string to describe an export.\n\n##### `Syntax`\n\nThe `|` or `%20` (space) allow to separate the `syntax`, `moduleName`, `name` and `alias` of import.\n\nString syntax - `[[syntax] [moduleName] [name] [alias]]` or `[[syntax]|[moduleName]|[name]|[alias]]`, where:\n\n- `[syntax]` (**may be omitted**):\n\n  - if `type` is `module`- can be `default`, `named`, `namespace` or `side-effects`, the default value is `default`.\n  - if `type` is `commonjs`- can be `single`, `multiple` or `pure`, the default value is `single`.\n\n- `[moduleName]` - name of an imported module (**required**)\n- `[name]` - name of an imported value (**required**)\n- `[alias]` - alias of an imported value (**may be omitted**)\n\nExamples:\n\nIf type `module`:\n\n- `[Foo]` - generates `import Foo from \"Foo\";`.\n- `[default Foo]` - generates `import Foo from \"Foo\";`.\n- `[default ./my-lib Foo]` - generates `import Foo from \"./my-lib\";`.\n- `[named Foo FooA]` - generates `import { FooA } from \"Foo\";`.\n- `[named Foo FooA Bar]` - generates `import { FooA as Bar } from \"Foo\";`.\n- `[namespace Foo FooA]` - generates `import * as FooA from \"Foo\";`.\n- `[side-effects Foo]` - generates `import \"Foo\";`.\n\nIf type `commonjs`:\n\n- `[Foo]` - generates `const Foo = require(\"Foo\");`.\n- `[single Foo]` - generates `const Foo = require(\"Foo\");`.\n- `[single ./my-lib Foo]` - generates `const Foo = require(\"./my-lib\");`.\n- `[multiple Foo FooA Bar]` - generates `const { FooA: Bar } = require(\"Foo\");`.\n- `[pure Foo]` - generates `require(\"Foo\");`.\n\n\u003e [!WARNING]\n\u003e\n\u003e You need to set `type: \"commonjs\"` to use `single`, `multiple` and `pure` syntaxes.\n\n\u003e [!WARNING]\n\u003e\n\u003e Aliases can't be used together with `default`, `namespace`, `side-effects`, `single` and `pure` syntaxes.\n\n###### Examples\n\n###### ES Module Default Import\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"./path/to/example.js\"),\n        loader: \"imports-loader\",\n        options: {\n          imports: \"default lib myName\",\n        },\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport myName from \"lib\";\n\n// ...\n// Code\n// ...\n```\n\n###### CommonJS Single Import\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"./path/to/example.js\"),\n        loader: \"imports-loader\",\n        options: {\n          type: \"commonjs\",\n          imports: \"single lib myName\",\n        },\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nvar myName = require(\"lib\");\n\n// ...\n// Code\n// ...\n```\n\n#### `object`\n\nAllows to use an object to describe an import.\n\nProperties:\n\n- `syntax`:\n\n  - if `type` is `module`- can be `default`, `named`, `namespace` or `side-effects`\n  - if `type` is `commonjs`- can be `single`, `multiple` or `pure`\n\n- `moduleName` - name of an imported module (**required**)\n- `name` - name of an imported value (**required**)\n- `alias` - alias of an imported value (**may be omitted**)\n\n\u003e [!WARNING]\n\u003e\n\u003e Alias can't be used together with `default`, `namespace`, `side-effects`, `single` and `pure` syntaxes.\n\n##### Examples\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: {\n                syntax: \"named\",\n                moduleName: \"lib_2\",\n                name: \"lib2_method_2\",\n                alias: \"lib_2_method_2_alias\",\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport { lib2_method_2 as lib_2_method_2_alias } from \"lib_2\";\n\n// ...\n// Code\n// ...\n```\n\n#### `array`\n\nAllow to specify multiple imports.\nEach item can be a [`string`](https://github.com/webpack-contrib/imports-loader#string) or an [`object`](https://github.com/webpack-contrib/imports-loader#object).\n\n##### Examples\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: [\n                {\n                  moduleName: \"angular\",\n                },\n                {\n                  syntax: \"default\",\n                  moduleName: \"jquery\",\n                  name: \"$\",\n                },\n                \"default lib_2 lib_2_default\",\n                \"named lib_2 lib2_method_1\",\n                \"named lib_2 lib2_method_2 lib_2_method_2_alias\",\n                \"namespace lib_3 lib_3_all\",\n                \"side-effects lib_4\",\n              ],\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport angular from \"angular\";\nimport $ from \"jquery\";\nimport lib_2_default from \"lib_2\";\nimport { lib2_method_1, lib2_method_2 as lib_2_method_2_alias } from \"lib_2\";\nimport * as lib_3_all from \"lib_3\";\nimport \"lib_4\";\n\n// ...\n// Code\n// ...\n```\n\n### `wrapper`\n\nType:\n\n```ts\ntype wrapper =\n  | boolean\n  | string\n  | {\n      thisArg: string;\n      args: Record\u003cstring, string\u003e | Array\u003cstring\u003e;\n    };\n```\n\nDefault: `undefined`\n\nCloses the module code in a function with a given `thisArg` and `args` (`(function () { ... }).call();`).\n\n\u003e [!WARNING]\n\u003e\n\u003e Do not use this option if source code contains ES module import(s)\n\n#### `boolean`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: {\n                moduleName: \"jquery\",\n                name: \"$\",\n              },\n              wrapper: true,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport $ from \"jquery\";\n\n(function () {\n  // ...\n  // Code\n  // ...\n}).call();\n```\n\n#### `string`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: {\n                moduleName: \"jquery\",\n                name: \"$\",\n              },\n              wrapper: \"window\",\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport $ from \"jquery\";\n\n(function () {\n  // ...\n  // Code\n  // ...\n}).call(window);\n```\n\n#### `object`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: {\n                moduleName: \"jquery\",\n                name: \"$\",\n              },\n              wrapper: {\n                thisArg: \"window\",\n                args: [\"myVariable\", \"myOtherVariable\"],\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport $ from \"jquery\";\n\n(function (myVariable, myOtherVariable) {\n  // ...\n  // Code\n  // ...\n}).call(window, myVariable, myOtherVariable);\n```\n\n#### `object` with different parameter names\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: {\n                moduleName: \"jquery\",\n                name: \"$\",\n              },\n              wrapper: {\n                thisArg: \"window\",\n                args: {\n                  myVariable: \"var1\",\n                  myOtherVariable: \"var2\",\n                },\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport $ from \"jquery\";\n\n(function (var1, var2) {\n  // ...\n  // Code\n  // ...\n}).call(window, myVariable, myOtherVariable);\n```\n\n### `additionalCode`\n\nType:\n\n```ts\ntype additionalCode = string;\n```\n\nDefault: `undefined`\n\nAdds custom code as a preamble before the module's code.\n\n##### Examples\n\n###### Define custom variable\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: {\n                moduleName: \"jquery\",\n                name: \"$\",\n              },\n              additionalCode: \"var myVariable = false;\",\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport $ from \"jquery\";\n\nvar myVariable = false;\n\n// ...\n// Code\n// ...\n```\n\n###### Disable AMD Import Syntax\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: require.resolve(\"example.js\"),\n        use: [\n          {\n            loader: \"imports-loader\",\n            options: {\n              imports: {\n                moduleName: \"jquery\",\n                name: \"$\",\n              },\n              additionalCode:\n                \"var define = false; /* Disable AMD for misbehaving libraries */\",\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nGenerate output:\n\n```js\nimport $ from \"jquery\";\n\nvar define = false; /* Disable AMD for misbehaving libraries */\n\n// ...\n// Code\n// ...\n```\n\n## Contributing\n\nPlease take a moment to read our contributing guidelines if you haven't yet done so.\n\n[CONTRIBUTING](./.github/CONTRIBUTING.md)\n\n## License\n\n[MIT](./LICENSE)\n\n[npm]: https://img.shields.io/npm/v/imports-loader.svg\n[npm-url]: https://www.npmjs.com/package/imports-loader\n[node]: https://img.shields.io/node/v/imports-loader.svg\n[node-url]: https://nodejs.org\n[tests]: https://github.com/webpack-contrib/imports-loader/workflows/imports-loader/badge.svg\n[tests-url]: https://github.com/webpack-contrib/imports-loader/actions\n[cover]: https://codecov.io/gh/webpack-contrib/imports-loader/branch/master/graph/badge.svg\n[cover-url]: https://codecov.io/gh/webpack-contrib/imports-loader\n[discussion]: https://img.shields.io/github/discussions/webpack/webpack\n[discussion-url]: https://github.com/webpack/webpack/discussions\n[size]: https://packagephobia.now.sh/badge?p=imports-loader\n[size-url]: https://packagephobia.now.sh/result?p=imports-loader\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fimports-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebpack-contrib%2Fimports-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fimports-loader/lists"}