{"id":13494544,"url":"https://github.com/webpack-contrib/file-loader","last_synced_at":"2026-03-20T00:29:53.192Z","repository":{"id":3218670,"uuid":"4253587","full_name":"webpack-contrib/file-loader","owner":"webpack-contrib","description":"File Loader","archived":true,"fork":false,"pushed_at":"2021-03-05T11:12:45.000Z","size":1348,"stargazers_count":1853,"open_issues_count":1,"forks_count":253,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-12-14T19:18:52.171Z","etag":null,"topics":["file","webpack","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},"funding":{"open_collective":"webpack"}},"created_at":"2012-05-07T20:13:12.000Z","updated_at":"2025-10-18T17:14:22.000Z","dependencies_parsed_at":"2022-08-06T13:16:25.398Z","dependency_job_id":null,"html_url":"https://github.com/webpack-contrib/file-loader","commit_stats":null,"previous_names":["webpack/file-loader"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/webpack-contrib/file-loader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Ffile-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Ffile-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Ffile-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Ffile-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webpack-contrib","download_url":"https://codeload.github.com/webpack-contrib/file-loader/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Ffile-loader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27758972,"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","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["file","webpack","webpack-loader"],"created_at":"2024-07-31T19:01:25.911Z","updated_at":"2025-12-18T03:04:36.941Z","avatar_url":"https://github.com/webpack-contrib.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/webpack/webpack\"\u003e\n    \u003cimg width=\"200\" height=\"200\" 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[![deps][deps]][deps-url]\n[![tests][tests]][tests-url]\n[![coverage][cover]][cover-url]\n[![chat][chat]][chat-url]\n[![size][size]][size-url]\n\n# file-loader\n\n**DEPRECATED for v5**: please consider migrating to [`asset modules`](https://webpack.js.org/guides/asset-modules/).\n\nThe `file-loader` resolves `import`/`require()` on a file into a url and emits the file into the output directory.\n\n## Getting Started\n\nTo begin, you'll need to install `file-loader`:\n\n```console\n$ npm install file-loader --save-dev\n```\n\nImport (or `require`) the target file(s) in one of the bundle's files:\n\n**file.js**\n\n```js\nimport img from './file.png';\n```\n\nThen add the loader to your `webpack` config. For example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        use: [\n          {\n            loader: 'file-loader',\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nAnd run `webpack` via your preferred method. This will emit `file.png` as a file\nin the output directory (with the specified naming convention, if options are\nspecified to do so) and returns the public URI of the file.\n\n\u003e ℹ️ By default the filename of the resulting file is the hash of the file's contents with the original extension of the required resource.\n\n## Options\n\n### `name`\n\nType: `String|Function`\nDefault: `'[contenthash].[ext]'`\n\nSpecifies a custom filename template for the target file(s) using the query\nparameter `name`. For example, to emit a file from your `context` directory into\nthe output directory retaining the full directory structure, you might use:\n\n#### `String`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          name: '[path][name].[ext]',\n        },\n      },\n    ],\n  },\n};\n```\n\n#### `Function`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          name(resourcePath, resourceQuery) {\n            // `resourcePath` - `/absolute/path/to/file.js`\n            // `resourceQuery` - `?foo=bar`\n\n            if (process.env.NODE_ENV === 'development') {\n              return '[path][name].[ext]';\n            }\n\n            return '[contenthash].[ext]';\n          },\n        },\n      },\n    ],\n  },\n};\n```\n\n\u003e ℹ️ By default the path and name you specify will output the file in that same directory, and will also use the same URI path to access the file.\n\n### `outputPath`\n\nType: `String|Function`\nDefault: `undefined`\n\nSpecify a filesystem path where the target file(s) will be placed.\n\n#### `String`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          outputPath: 'images',\n        },\n      },\n    ],\n  },\n};\n```\n\n#### `Function`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          outputPath: (url, resourcePath, context) =\u003e {\n            // `resourcePath` is original absolute path to asset\n            // `context` is directory where stored asset (`rootContext`) or `context` option\n\n            // To get relative path you can use\n            // const relativePath = path.relative(context, resourcePath);\n\n            if (/my-custom-image\\.png/.test(resourcePath)) {\n              return `other_output_path/${url}`;\n            }\n\n            if (/images/.test(context)) {\n              return `image_output_path/${url}`;\n            }\n\n            return `output_path/${url}`;\n          },\n        },\n      },\n    ],\n  },\n};\n```\n\n### `publicPath`\n\nType: `String|Function`\nDefault: [`__webpack_public_path__`](https://webpack.js.org/api/module-variables/#__webpack_public_path__-webpack-specific-)+outputPath\n\nSpecifies a custom public path for the target file(s).\n\n#### `String`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          publicPath: 'assets',\n        },\n      },\n    ],\n  },\n};\n```\n\n#### `Function`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          publicPath: (url, resourcePath, context) =\u003e {\n            // `resourcePath` is original absolute path to asset\n            // `context` is directory where stored asset (`rootContext`) or `context` option\n\n            // To get relative path you can use\n            // const relativePath = path.relative(context, resourcePath);\n\n            if (/my-custom-image\\.png/.test(resourcePath)) {\n              return `other_public_path/${url}`;\n            }\n\n            if (/images/.test(context)) {\n              return `image_output_path/${url}`;\n            }\n\n            return `public_path/${url}`;\n          },\n        },\n      },\n    ],\n  },\n};\n```\n\n### `postTransformPublicPath`\n\nType: `Function`\nDefault: `undefined`\n\nSpecifies a custom function to post-process the generated public path. This can be used to prepend or append dynamic global variables that are only available at runtime, like `__webpack_public_path__`. This would not be possible with just `publicPath`, since it stringifies the values.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpg|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          publicPath: '/some/path/',\n          postTransformPublicPath: (p) =\u003e `__webpack_public_path__ + ${p}`,\n        },\n      },\n    ],\n  },\n};\n```\n\n### `context`\n\nType: `String`\nDefault: [`context`](https://webpack.js.org/configuration/entry-context/#context)\n\nSpecifies a custom file context.\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              context: 'project',\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `emitFile`\n\nType: `Boolean`\nDefault: `true`\n\nIf true, emits a file (writes a file to the filesystem). If false, the loader\nwill return a public URI but **will not** emit the file. It is often useful to\ndisable this option for server-side packages.\n\n**file.js**\n\n```js\n// bundle file\nimport img from './file.png';\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.css$/i,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              emitFile: false,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `regExp`\n\nType: `RegExp`\nDefault: `undefined`\n\nSpecifies a Regular Expression to one or many parts of the target file path.\nThe capture groups can be reused in the `name` property using `[N]`\n[placeholder](https://github.com/webpack-contrib/file-loader#placeholders).\n\n**file.js**\n\n```js\nimport img from './customer01/file.png';\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              regExp: /\\/([a-z0-9]+)\\/[a-z0-9]+\\.png$/i,\n              name: '[1]-[name].[ext]',\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n\u003e ℹ️ If `[0]` is used, it will be replaced by the entire tested string, whereas `[1]` will contain the first capturing parenthesis of your regex and so on...\n\n### `esModule`\n\nType: `Boolean`\nDefault: `true`\n\nBy default, `file-loader` generates JS modules that use the ES modules syntax.\nThere are some cases in which using ES modules is beneficial, like in the case of [module concatenation](https://webpack.js.org/plugins/module-concatenation-plugin/) and [tree shaking](https://webpack.js.org/guides/tree-shaking/).\n\nYou can enable a CommonJS module syntax using:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.css$/,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              esModule: false,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n## Placeholders\n\nFull information about placeholders you can find [here](https://github.com/webpack/loader-utils#interpolatename).\n\n### `[ext]`\n\nType: `String`\nDefault: `file.extname`\n\nThe file extension of the target file/resource.\n\n### `[name]`\n\nType: `String`\nDefault: `file.basename`\n\nThe basename of the file/resource.\n\n### `[path]`\n\nType: `String`\nDefault: `file.directory`\n\nThe path of the resource relative to the webpack/config `context`.\n\n### `[folder]`\n\nType: `String`\nDefault: `file.folder`\n\nThe folder of the resource is in.\n\n### `[query]`\n\nType: `String`\nDefault: `file.query`\n\nThe query of the resource, i.e. `?foo=bar`.\n\n### `[emoji]`\n\nType: `String`\nDefault: `undefined`\n\nA random emoji representation of `content`.\n\n### `[emoji:\u003clength\u003e]`\n\nType: `String`\nDefault: `undefined`\n\nSame as above, but with a customizable number of emojis\n\n### `[hash]`\n\nType: `String`\nDefault: `md4`\n\nSpecifies the hash method to use for hashing the file content.\n\n### `[contenthash]`\n\nType: `String`\nDefault: `md4`\n\nSpecifies the hash method to use for hashing the file content.\n\n### `[\u003chashType\u003e:hash:\u003cdigestType\u003e:\u003clength\u003e]`\n\nType: `String`\n\nThe hash of options.content (Buffer) (by default it's the hex digest of the hash).\n\n#### `digestType`\n\nType: `String`\nDefault: `'hex'`\n\nThe [digest](https://en.wikipedia.org/wiki/Cryptographic_hash_function) that the\nhash function should use. Valid values include: base26, base32, base36,\nbase49, base52, base58, base62, base64, and hex.\n\n#### `hashType`\n\nType: `String`\nDefault: `'md4'`\n\nThe type of hash that the hash function should use. Valid values include: `md4`, `md5`, `sha1`, `sha256`, and `sha512`.\n\n#### `length`\n\nType: `Number`\nDefault: `undefined`\n\nUsers may also specify a length for the computed hash.\n\n### `[N]`\n\nType: `String`\nDefault: `undefined`\n\nThe n-th match obtained from matching the current file name against the `regExp`.\n\n## Examples\n\n### Names\n\nThe following examples show how one might use `file-loader` and what the result would be.\n\n**file.js**\n\n```js\nimport png from './image.png';\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              name: 'dirname/[contenthash].[ext]',\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nResult:\n\n```bash\n# result\ndirname/0dcbbaa701328ae351f.png\n```\n\n---\n\n**file.js**\n\n```js\nimport png from './image.png';\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              name: '[sha512:hash:base64:7].[ext]',\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nResult:\n\n```bash\n# result\ngdyb21L.png\n```\n\n---\n\n**file.js**\n\n```js\nimport png from './path/to/file.png';\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              name: '[path][name].[ext]?[contenthash]',\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nResult:\n\n```bash\n# result\npath/to/file.png?e43b20c069c4a01867c31e98cbce33c9\n```\n\n### CDN\n\nThe following examples show how to use `file-loader` for CDN uses query params.\n\n**file.js**\n\n```js\nimport png from './directory/image.png?width=300\u0026height=300';\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  output: {\n    publicPath: 'https://cdn.example.com/',\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpe?g|gif)$/i,\n        use: [\n          {\n            loader: 'file-loader',\n            options: {\n              name: '[path][name].[ext][query]',\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nResult:\n\n```bash\n# result\nhttps://cdn.example.com/directory/image.png?width=300\u0026height=300\n```\n\n### Dynamic public path depending on environment variable at run time\n\nAn application might want to configure different CDN hosts depending on an environment variable that is only available when running the application. This can be an advantage, as only one build of the application is necessary, which behaves differently depending on environment variables of the deployment environment. Since file-loader is applied when compiling the application, and not when running it, the environment variable cannot be used in the file-loader configuration. A way around this is setting the `__webpack_public_path__` to the desired CDN host depending on the environment variable at the entrypoint of the application. The option `postTransformPublicPath` can be used to configure a custom path depending on a variable like `__webpack_public_path__`.\n\n**main.js**\n\n```js\nconst assetPrefixForNamespace = (namespace) =\u003e {\n  switch (namespace) {\n    case 'prod':\n      return 'https://cache.myserver.net/web';\n    case 'uat':\n      return 'https://cache-uat.myserver.net/web';\n    case 'st':\n      return 'https://cache-st.myserver.net/web';\n    case 'dev':\n      return 'https://cache-dev.myserver.net/web';\n    default:\n      return '';\n  }\n};\nconst namespace = process.env.NAMESPACE;\n\n__webpack_public_path__ = `${assetPrefixForNamespace(namespace)}/`;\n```\n\n**file.js**\n\n```js\nimport png from './image.png';\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpg|gif)$/i,\n        loader: 'file-loader',\n        options: {\n          name: '[name].[contenthash].[ext]',\n          outputPath: 'static/assets/',\n          publicPath: 'static/assets/',\n          postTransformPublicPath: (p) =\u003e `__webpack_public_path__ + ${p}`,\n        },\n      },\n    ],\n  },\n};\n```\n\nResult when run with `NAMESPACE=prod` env variable:\n\n```bash\n# result\nhttps://cache.myserver.net/web/static/assets/image.somehash.png\n```\n\nResult when run with `NAMESPACE=dev` env variable:\n\n```bash\n# result\nhttps://cache-dev.myserver.net/web/static/assets/image.somehash.png\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/file-loader.svg\n[npm-url]: https://npmjs.com/package/file-loader\n[node]: https://img.shields.io/node/v/file-loader.svg\n[node-url]: https://nodejs.org\n[deps]: https://david-dm.org/webpack-contrib/file-loader.svg\n[deps-url]: https://david-dm.org/webpack-contrib/file-loader\n[tests]: https://github.com/webpack-contrib/file-loader/workflows/file-loader/badge.svg\n[tests-url]: https://github.com/webpack-contrib/file-loader/actions\n[cover]: https://codecov.io/gh/webpack-contrib/file-loader/branch/master/graph/badge.svg\n[cover-url]: https://codecov.io/gh/webpack-contrib/file-loader\n[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg\n[chat-url]: https://gitter.im/webpack/webpack\n[size]: https://packagephobia.now.sh/badge?p=file-loader\n[size-url]: https://packagephobia.now.sh/result?p=file-loader\n","funding_links":["https://opencollective.com/webpack"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Ffile-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebpack-contrib%2Ffile-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Ffile-loader/lists"}