file-loader vs url-loader vs raw-loader vs image-webpack-loader
Webpack Asset Loaders for Handling Non-JavaScript Files
Search packages..
file-loaderurl-loaderraw-loaderimage-webpack-loaderSimilar Packages:
Webpack Asset Loaders for Handling Non-JavaScript Files

file-loader, image-webpack-loader, raw-loader, and url-loader are Webpack loaders designed to handle non-JavaScript assets during the build process. file-loader emits files to the output directory and returns their public paths, url-loader conditionally inlines small files as Data URLs, raw-loader imports file contents as strings, and image-webpack-loader compresses and optimizes image assets. However, as of Webpack 5, file-loader, raw-loader, and url-loader are officially deprecated in favor of Webpack's built-in Asset Modules, while image-webpack-loader remains actively maintained for image optimization tasks.

Npm Package Weekly Downloads Trend
3 Years
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
file-loader10,333,0911,853-15 years agoMIT
url-loader4,986,2841,404-45 years agoMIT
raw-loader3,476,181845-55 years agoMIT
image-webpack-loader106,5402,0243.56 MB81-MIT

Webpack Asset Loaders: file-loader, image-webpack-loader, raw-loader, and url-loader Compared

These four loaders — file-loader, image-webpack-loader, raw-loader, and url-loader — are all designed to help Webpack handle non-JavaScript assets during the build process. However, they serve very different purposes, and some have been deprecated in favor of newer Webpack features. Understanding when and how to use each is critical for optimizing asset handling, bundle size, and developer experience.

⚠️ Deprecation Status: A Critical Starting Point

Before diving into functionality, it’s essential to note that three of these four packages are officially deprecated:

Only image-webpack-loader remains actively maintained — but it serves a completely different role: image optimization, not asset resolution.

🛑 Do not use file-loader, raw-loader, or url-loader in new Webpack 5+ projects. They exist only for legacy compatibility.

📦 Core Purpose: What Each Loader Actually Does

file-loader: Emit files to output directory

file-loader copies a file to your output directory and returns its public path as a string. It was commonly used for images, fonts, or other static assets that should live as separate files.

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

// In code
import img from './image.png';
console.log(img); // e.g., '/static/media/image.abc123.png'

url-loader: Inline small files as Data URLs

url-loader works like file-loader, but with a twist: if a file is smaller than a configured limit, it returns a base64-encoded Data URL instead of emitting a file. This avoids extra HTTP requests for tiny assets.

// webpack.config.js (legacy)
{
  test: /\.(png|jpe?g|gif)$/i,
  use: [
    {
      loader: 'url-loader',
      options: { limit: 8192 } // 8 KB
    }
  ]
}

// For small image → returns 'data:image/png;base64,...'
// For large image → falls back to file-loader behavior

raw-loader: Import file contents as a string

raw-loader reads a file and exports its raw content as a JavaScript string. Useful for importing text files, SVGs, or shader code without parsing.

// webpack.config.js (legacy)
{
  test: /\.txt$/,
  use: 'raw-loader'
}

// In code
import license from './LICENSE.txt';
console.log(typeof license); // 'string'

image-webpack-loader: Optimize image assets

Unlike the others, image-webpack-loader doesn’t change how assets are resolved — it compresses and optimizes images using tools like mozjpeg, pngquant, and svgo. It’s typically chained after another loader.

// webpack.config.js (still valid)
{
  test: /\.(png|jpe?g|gif|svg)$/i,
  use: [
    'file-loader', // or Webpack 5 asset module
    {
      loader: 'image-webpack-loader',
      options: {
        mozjpeg: { quality: 80 },
        pngquant: { quality: [0.6, 0.8] }
      }
    }
  ]
}

🔧 Modern Webpack 5 Replacement Patterns

Webpack 5 introduced Asset Modules, which eliminate the need for file-loader, url-loader, and raw-loader. Here’s how to migrate:

Replace file-loader → type: 'asset/resource'

// Modern equivalent
{
  test: /\.(png|jpg|gif)$/i,
  type: 'asset/resource'
}

Replace url-loader → type: 'asset' with parser.dataUrlCondition

// Modern equivalent
{
  test: /\.(png|jpg|gif)$/i,
  type: 'asset',
  parser: {
    dataUrlCondition: { maxSize: 8 * 1024 } // 8 KB
  }
}

Replace raw-loader → type: 'asset/source'

// Modern equivalent
{
  test: /\.txt$/,
  type: 'asset/source'
}

💡 You can still use image-webpack-loader with these modern asset types — just place it in the use array alongside them.

🖼️ Real-World Image Handling Strategy

Here’s how you’d configure image loading and optimization in a modern Webpack 5 project:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif|svg)$/i,
        type: 'asset',
        parser: {
          dataUrlCondition: { maxSize: 4 * 1024 } // Inline <4KB
        },
        generator: {
          filename: 'images/[name].[hash][ext]'
        },
        use: [
          {
            loader: 'image-webpack-loader',
            options: {
              disable: process.env.NODE_ENV === 'development',
              mozjpeg: { progressive: true, quality: 75 },
              optipng: { enabled: false },
              pngquant: { quality: [0.65, 0.8], speed: 4 },
              svgo: { plugins: [{ removeViewBox: false }] }
            }
          }
        ]
      }
    ]
  }
};

This setup:

  • Inlines tiny images as Data URLs (reducing HTTP requests)
  • Emits larger images as optimized files in /images/
  • Skips compression in development for faster builds
  • Uses up-to-date Webpack 5 APIs

🧩 When to Use image-webpack-loader Today

Since the other three loaders are deprecated, the only relevant decision is whether to include image-webpack-loader:

✅ Use it if:

  • You serve unoptimized images from designers or CMS uploads
  • Bundle size or page weight is a performance concern
  • You want automated lossy/lossless compression

❌ Skip it if:

  • Your images are already pre-optimized
  • You’re using a CDN with built-in image optimization (e.g., Cloudflare Images, Imgix)
  • Build time is more critical than output size (it adds significant processing time)

🔄 Migration Path for Legacy Projects

If you’re maintaining a Webpack 4 project:

  1. Do not add new dependencies on file-loader, url-loader, or raw-loader.
  2. When upgrading to Webpack 5, replace them with asset modules as shown above.
  3. Keep image-webpack-loader if you rely on its optimization — it works fine with Webpack 5 asset modules.

📌 Summary Table

PackageStatusPurposeWebpack 5 Replacement
file-loader❌ DeprecatedEmit file, return public pathtype: 'asset/resource'
url-loader❌ DeprecatedInline small files as Data URLstype: 'asset' + dataUrlCondition
raw-loader❌ DeprecatedImport file contents as stringtype: 'asset/source'
image-webpack-loader✅ ActiveCompress/optimize image assetsNo replacement needed

💡 Final Recommendation

For new projects, skip the deprecated loaders entirely and use Webpack 5’s built-in asset modules. Add image-webpack-loader only if you need on-the-fly image optimization and don’t have a better solution (like a smart CDN).

For existing projects, plan a migration away from the deprecated loaders when moving to Webpack 5. The configuration changes are straightforward, and you’ll benefit from reduced dependencies and better integration with Webpack’s core.

How to Choose: file-loader vs url-loader vs raw-loader vs image-webpack-loader
  • file-loader:

    Do not use file-loader in new Webpack 5+ projects — it is officially deprecated. Instead, use Webpack’s built-in type: 'asset/resource' to emit files to the output directory. Only consider this package if you’re maintaining a legacy Webpack 4 project and cannot upgrade immediately.

  • url-loader:

    Do not use url-loader in modern Webpack projects — it’s deprecated. Replace it with type: 'asset' combined with parser.dataUrlCondition.maxSize to inline small assets as Data URLs. Its functionality is now natively supported without extra dependencies.

  • raw-loader:

    Avoid raw-loader in new projects — it’s deprecated as of Webpack 5. Use type: 'asset/source' instead to import file contents as strings. This package should only be used in legacy Webpack 4 codebases where migration isn’t feasible yet.

  • image-webpack-loader:

    Choose image-webpack-loader when you need automated, build-time image optimization (compression, resizing, format conversion) and don’t have a CDN or external service handling it. It works well alongside Webpack 5’s asset modules and is the only actively maintained package among the four. Avoid it if your images are already optimized or if build performance is more critical than output size.

Similar Npm Packages to file-loader

file-loader is a webpack loader that helps in managing and loading files in your web applications. It allows you to import files, such as images, fonts, and other assets, directly into your JavaScript modules. When you use file-loader, it processes these files and emits them to the output directory, providing a URL to access them in your application. This is particularly useful for optimizing asset management and ensuring that your files are correctly bundled during the build process.

While file-loader is a great tool for handling file imports, there are alternatives that can also help manage assets in a webpack environment. Here are a couple of notable alternatives:

  • copy-webpack-plugin is a webpack plugin that allows you to copy files and directories from one location to another during the build process. Unlike file-loader, which processes files and returns URLs for use in your application, copy-webpack-plugin simply copies files to the output directory without modifying them. This is useful when you want to include static assets that do not need to be processed or transformed, such as HTML files or images that are referenced directly in your code.
  • url-loader is another webpack loader that works similarly to file-loader but with an added feature: it can convert files into base64-encoded URLs if they are below a specified size limit. This can reduce the number of HTTP requests made by your application and improve performance for smaller assets. If you prefer to inline small files directly into your JavaScript, url-loader can be a great alternative to file-loader.

To see how file-loader compares with copy-webpack-plugin and url-loader, check out the comparison: Comparing copy-webpack-plugin vs file-loader vs url-loader.

Similar Npm Packages to url-loader

url-loader is a Webpack loader that allows you to convert files into base64 URIs. This is particularly useful for small files, as it can help reduce the number of HTTP requests by inlining the files directly into your JavaScript or CSS. By using url-loader, developers can optimize their applications by bundling smaller assets, which can lead to improved performance and faster load times.

While url-loader is a powerful tool for handling file assets, there are several alternatives that can also be utilized for similar purposes:

  • file-loader is a Webpack loader that allows you to import files into your JavaScript modules. Unlike url-loader, which inlines files as base64 URIs, file-loader emits the files to the output directory and returns the public URL of the file. This is useful for larger files where inlining may not be practical. If you want to manage file assets without inlining them, file-loader is a solid choice.
  • image-webpack-loader is specifically designed for optimizing images in Webpack. It can compress and optimize images in various formats, making it an excellent choice for image-heavy applications. This loader works in conjunction with other loaders, such as file-loader or url-loader, to ensure that images are not only loaded but also optimized for performance. If your project heavily relies on images and you want to ensure they are optimized, image-webpack-loader is the way to go.
  • raw-loader is another Webpack loader that allows you to import files as strings. This is particularly useful for text files, such as markdown or HTML, where you want to include the raw content directly in your JavaScript. While raw-loader does not handle binary files like images or fonts, it provides a straightforward way to work with text-based assets. If your project involves a lot of text files and you need to include their content directly, raw-loader is a great option.

To see how url-loader compares with file-loader, image-webpack-loader, and raw-loader, check out the comparison: Comparing file-loader vs image-webpack-loader vs raw-loader vs url-loader.

README for file-loader

npm node deps tests coverage chat size

file-loader

The file-loader resolves import/require() on a file into a url and emits the file into the output directory.

Getting Started

To begin, you'll need to install file-loader:

$ npm install file-loader --save-dev

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

file.js

import img from './file.png';

Then add the loader to your webpack config. For example:

webpack.config.js

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

And run webpack via your preferred method. This will emit file.png as a file in the output directory (with the specified naming convention, if options are specified 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.

Options

name

Type: String|Function Default: '[contenthash].[ext]'

Specifies a custom filename template for the target file(s) using the query parameter name. For example, to emit a file from your context directory into the output directory retaining the full directory structure, you might use:

String

webpack.config.js

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

Function

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.

outputPath

Type: String|Function Default: undefined

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

String

webpack.config.js

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

Function

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}`;
          },
        },
      },
    ],
  },
};

publicPath

Type: String|Function Default: __webpack_public_path__+outputPath

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

String

webpack.config.js

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

Function

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}`;
          },
        },
      },
    ],
  },
};

postTransformPublicPath

Type: Function Default: 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 just publicPath, 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}`,
        },
      },
    ],
  },
};

context

Type: String Default: context

Specifies a custom file context.

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

emitFile

Type: Boolean Default: true

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

file.js

// bundle file
import img from './file.png';

webpack.config.js

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

regExp

Type: RegExp Default: undefined

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

file.js

import img from './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...

esModule

Type: Boolean Default: 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 of module concatenation and tree 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,
            },
          },
        ],
      },
    ],
  },
};

Placeholders

Full information about placeholders you can find here.

[ext]

Type: String Default: file.extname

The file extension of the target file/resource.

[name]

Type: String Default: file.basename

The basename of the file/resource.

[path]

Type: String Default: file.directory

The path of the resource relative to the webpack/config context.

[folder]

Type: String Default: file.folder

The folder of the resource is in.

[query]

Type: String Default: file.query

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

[emoji]

Type: String Default: undefined

A random emoji representation of content.

[emoji:<length>]

Type: String Default: undefined

Same as above, but with a customizable number of emojis

[hash]

Type: String Default: md4

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

[contenthash]

Type: String Default: md4

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

[<hashType>:hash:<digestType>:<length>]

Type: String

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

digestType

Type: String Default: 'hex'

The digest that the hash function should use. Valid values include: base26, base32, base36, base49, base52, base58, base62, base64, and hex.

hashType

Type: String Default: 'md4'

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

length

Type: Number Default: undefined

Users may also specify a length for the computed hash.

[N]

Type: String Default: undefined

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

Examples

Names

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

file.js

import png from './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:

# result
dirname/0dcbbaa701328ae351f.png

file.js

import png from './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:

# result
gdyb21L.png

file.js

import png from './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:

# result
path/to/file.png?e43b20c069c4a01867c31e98cbce33c9

CDN

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

file.js

import png from './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:

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

Dynamic public path depending on environment variable at run time

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 option postTransformPublicPath can be used to configure a custom path depending on a variable like __webpack_public_path__.

main.js

const assetPrefixForNamespace = (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 '';
  }
};
const namespace = process.env.NAMESPACE;

__webpack_public_path__ = `${assetPrefixForNamespace(namespace)}/`;

file.js

import png from './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 with NAMESPACE=prod env variable:

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

Result when run with NAMESPACE=dev env variable:

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

Contributing

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

CONTRIBUTING

License

MIT

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.