Repository files navigation

DEPRECATED for v5: please consider migrating toasset modules.

Thefile-loader resolvesimport/require() on a file into a url and emits the file into the output directory.

To begin, you'll need to installfile-loader:

$npm install file-loader --save-dev

Import (orrequire) the target file(s) in one of the bundle's files:

file.js

importimgfrom'./file.png';

Then add the loader to yourwebpack config. For example:

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,use:[{loader:'file-loader',},],},],},};

And runwebpack via your preferred method. This will emitfile.png as a filein the output directory (with the specified naming convention, if options arespecified to do so) and returns the public URI of the file.

ℹ️ By default the filename of the resulting file is the hash of the file's contents with the original extension of the required resource.

Type:String|FunctionDefault:'[contenthash].[ext]'

Specifies a custom filename template for the target file(s) using the queryparametername. For example, to emit a file from yourcontext directory intothe output directory retaining the full directory structure, you might use:

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,loader:'file-loader',options:{name:'[path][name].[ext]',},},],},};

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,loader:'file-loader',options:{name(resourcePath,resourceQuery){// `resourcePath` - `/absolute/path/to/file.js`// `resourceQuery` - `?foo=bar`if(process.env.NODE_ENV==='development'){return'[path][name].[ext]';}return'[contenthash].[ext]';},},},],},};

ℹ️ 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.

Type:String|FunctionDefault:undefined

Specify a filesystem path where the target file(s) will be placed.

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,loader:'file-loader',options:{outputPath:'images',},},],},};

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,loader:'file-loader',options:{outputPath:(url,resourcePath,context)=>{// `resourcePath` is original absolute path to asset// `context` is directory where stored asset (`rootContext`) or `context` option// To get relative path you can use// const relativePath = path.relative(context, resourcePath);if(/my-custom-image\.png/.test(resourcePath)){return`other_output_path/${url}`;}if(/images/.test(context)){return`image_output_path/${url}`;}return`output_path/${url}`;},},},],},};

Type:String|FunctionDefault:__webpack_public_path__+outputPath

Specifies a custom public path for the target file(s).

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,loader:'file-loader',options:{publicPath:'assets',},},],},};

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,loader:'file-loader',options:{publicPath:(url,resourcePath,context)=>{// `resourcePath` is original absolute path to asset// `context` is directory where stored asset (`rootContext`) or `context` option// To get relative path you can use// const relativePath = path.relative(context, resourcePath);if(/my-custom-image\.png/.test(resourcePath)){return`other_public_path/${url}`;}if(/images/.test(context)){return`image_output_path/${url}`;}return`public_path/${url}`;},},},],},};

Type:FunctionDefault:undefined

Specifies 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 justpublicPath, since it stringifies the values.

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpg|gif)$/i,loader:'file-loader',options:{publicPath:'/some/path/',postTransformPublicPath:(p)=>`__webpack_public_path__ +${p}`,},},],},};

Type:StringDefault:context

Specifies a custom file context.

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,use:[{loader:'file-loader',options:{context:'project',},},],},],},};

Type:BooleanDefault:true

If true, emits a file (writes a file to the filesystem). If false, the loaderwill return a public URI butwill not emit the file. It is often useful todisable this option for server-side packages.

file.js

// bundle fileimportimgfrom'./file.png';

webpack.config.js

module.exports={module:{rules:[{test:/\.css$/i,use:[{loader:'file-loader',options:{emitFile:false,},},],},],},};

Type:RegExpDefault:undefined

Specifies a Regular Expression to one or many parts of the target file path.The capture groups can be reused in thename property using[N]placeholder.

file.js

importimgfrom'./customer01/file.png';

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,use:[{loader:'file-loader',options:{regExp:/\/([a-z0-9]+)\/[a-z0-9]+\.png$/i,name:'[1]-[name].[ext]',},},],},],},};

ℹ️ 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...

Type:BooleanDefault:true

By default,file-loader generates JS modules that use the ES modules syntax.There are some cases in which using ES modules is beneficial, like in the case ofmodule concatenation andtree shaking.

You can enable a CommonJS module syntax using:

webpack.config.js

module.exports={module:{rules:[{test:/\.css$/,use:[{loader:'file-loader',options:{esModule:false,},},],},],},};

Full information about placeholders you can findhere.

Type:StringDefault:file.extname

The file extension of the target file/resource.

Type:StringDefault:file.basename

The basename of the file/resource.

Type:StringDefault:file.directory

The path of the resource relative to the webpack/configcontext.

Type:StringDefault:file.folder

The folder of the resource is in.

Type:StringDefault:file.query

The query of the resource, i.e.?foo=bar.

Type:StringDefault:undefined

A random emoji representation ofcontent.

Type:StringDefault:undefined

Same as above, but with a customizable number of emojis

Type:StringDefault:md4

Specifies the hash method to use for hashing the file content.

Type:StringDefault:md4

Specifies the hash method to use for hashing the file content.

Type:String

The hash of options.content (Buffer) (by default it's the hex digest of the hash).

Type:StringDefault:'hex'

Thedigest that thehash function should use. Valid values include: base26, base32, base36,base49, base52, base58, base62, base64, and hex.

Type:StringDefault:'md4'

The type of hash that the hash function should use. Valid values include:md4,md5,sha1,sha256, andsha512.

Type:NumberDefault:undefined

Users may also specify a length for the computed hash.

Type:StringDefault:undefined

The n-th match obtained from matching the current file name against theregExp.

The following examples show how one might usefile-loader and what the result would be.

file.js

importpngfrom'./image.png';

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,use:[{loader:'file-loader',options:{name:'dirname/[contenthash].[ext]',},},],},],},};

Result:

# resultdirname/0dcbbaa701328ae351f.png

file.js

importpngfrom'./image.png';

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,use:[{loader:'file-loader',options:{name:'[sha512:hash:base64:7].[ext]',},},],},],},};

Result:

# resultgdyb21L.png

file.js

importpngfrom'./path/to/file.png';

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpe?g|gif)$/i,use:[{loader:'file-loader',options:{name:'[path][name].[ext]?[contenthash]',},},],},],},};

Result:

# resultpath/to/file.png?e43b20c069c4a01867c31e98cbce33c9

The following examples show how to usefile-loader for CDN uses query params.

file.js

importpngfrom'./directory/image.png?width=300&height=300';

webpack.config.js

module.exports={output:{publicPath:'https://cdn.example.com/',},module:{rules:[{test:/\.(png|jpe?g|gif)$/i,use:[{loader:'file-loader',options:{name:'[path][name].[ext][query]',},},],},],},};

Result:

# resulthttps://cdn.example.com/directory/image.png?width=300&height=300

An 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 optionpostTransformPublicPath can be used to configure a custom path depending on a variable like__webpack_public_path__.

main.js

constassetPrefixForNamespace=(namespace)=>{switch(namespace){case'prod':return'https://cache.myserver.net/web';case'uat':return'https://cache-uat.myserver.net/web';case'st':return'https://cache-st.myserver.net/web';case'dev':return'https://cache-dev.myserver.net/web';default:return'';}};constnamespace=process.env.NAMESPACE;__webpack_public_path__=`${assetPrefixForNamespace(namespace)}/`;

file.js

importpngfrom'./image.png';

webpack.config.js

module.exports={module:{rules:[{test:/\.(png|jpg|gif)$/i,loader:'file-loader',options:{name:'[name].[contenthash].[ext]',outputPath:'static/assets/',publicPath:'static/assets/',postTransformPublicPath:(p)=>`__webpack_public_path__ +${p}`,},},],},};

Result when run withNAMESPACE=prod env variable:

# resulthttps://cache.myserver.net/web/static/assets/image.somehash.png

Result when run withNAMESPACE=dev env variable:

# resulthttps://cache-dev.myserver.net/web/static/assets/image.somehash.png

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

MIT