ag-grid is proud to partner with webpack

Printable

babel-loader

This package allows transpiling JavaScript files using Babel and webpack.

Note: Issues with the output should be reported on the Babel Issues tracker.

Install

webpack 4.x | babel-loader 8.x | babel 7.x

npm install -D babel-loader @babel/core @babel/preset-env webpack

Usage

webpack documentation: Loaders

Within your webpack configuration object, you'll need to add the babel-loader to the list of modules, like so:

module: {
  rules: [
    {
      test: /\.m?js$/,
      exclude: /(node_modules|bower_components)/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env']
        }
      }
    }
  ]
}

Options

See the babel options.

You can pass options to the loader by using the options property:

module: {
  rules: [
    {
      test: /\.m?js$/,
      exclude: /(node_modules|bower_components)/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env'],
          plugins: ['@babel/plugin-proposal-object-rest-spread']
        }
      }
    }
  ]
}

This loader also supports the following loader-specific option:

cacheDirectory: Default false. When set, the given directory will be used to cache the results of the loader. Future webpack builds will attempt to read from the cache to avoid needing to run the potentially expensive Babel recompilation process on each run. If the value is set to true in options ({cacheDirectory: true}), the loader will use the default cache directory in node_modules/.cache/babel-loader or fallback to the default OS temporary file directory if no node_modules folder could be found in any root directory.
cacheIdentifier: Default is a string composed by the @babel/core's version, the babel-loader's version, the contents of .babelrc file if it exists, and the value of the environment variable BABEL_ENV with a fallback to the NODE_ENV environment variable. This can be set to a custom value to force cache busting if the identifier changes.
cacheCompression: Default true. When set, each Babel transform output will be compressed with Gzip. If you want to opt-out of cache compression, set it to false -- your project may benefit from this if it transpiles thousands of files.
customize: Default null. The path of a module that exports a custom callback like the one that you'd pass to .custom(). Since you already have to make a new file to use this, it is recommended that you instead use .custom to create a wrapper loader. Only use this if you must continue using babel-loader directly, but still want to customize.

Troubleshooting

babel-loader is slow!

Make sure you are transforming as few files as possible. Because you are probably matching /\.m?js$/, you might be transforming the node_modules folder or other unwanted source.

To exclude node_modules, see the exclude option in the loaders config as documented above.

You can also speed up babel-loader by as much as 2x by using the cacheDirectory option. This will cache transformations to the filesystem.

Babel is injecting helpers into each file and bloating my code!

Babel uses very small helpers for common functions such as _extend. By default, this will be added to every file that requires it.

You can instead require the Babel runtime as a separate module to avoid the duplication.

The following configuration disables automatic per-file runtime injection in Babel, requiring @babel/plugin-transform-runtime instead and making all helper references use it.

See the docs for more information.

NOTE: You must run npm install -D @babel/plugin-transform-runtime to include this in your project and @babel/runtime itself as a dependency with npm install @babel/runtime.

rules: [
  // the 'transform-runtime' plugin tells Babel to
  // require the runtime instead of inlining it.
  {
    test: /\.m?js$/,
    exclude: /(node_modules|bower_components)/,
    use: {
      loader: 'babel-loader',
      options: {
        presets: ['@babel/preset-env'],
        plugins: ['@babel/plugin-transform-runtime']
      }
    }
  }
]

NOTE: transform-runtime & custom polyfills (e.g. Promise library)

Since @babel/plugin-transform-runtime includes a polyfill that includes a custom regenerator-runtime and core-js, the following usual shimming method using webpack.ProvidePlugin will not work:

// ...
        new webpack.ProvidePlugin({
            'Promise': 'bluebird'
        }),
// ...

The following approach will not work either:

require('@babel/runtime/core-js/promise').default = require('bluebird');

var promise = new Promise;

which outputs to (using runtime):

'use strict';

var _Promise = require('@babel/runtime/core-js/promise')['default'];

require('@babel/runtime/core-js/promise')['default'] = require('bluebird');

var promise = new _Promise();

The previous Promise library is referenced and used before it is overridden.

One approach is to have a "bootstrap" step in your application that would first override the default globals before your application:

// bootstrap.js

require('@babel/runtime/core-js/promise').default = require('bluebird');

// ...

require('./app');

The Node.js API for `babel` has been moved to `babel-core`.

If you receive this message, it means that you have the npm package babel installed and are using the short notation of the loader in the webpack config (which is not valid anymore as of webpack 2.x):

  {
    test: /\.m?js$/,
    loader: 'babel',
  }

webpack then tries to load the babel package instead of the babel-loader.

To fix this, you should uninstall the npm package babel, as it is deprecated in Babel v6. (Instead, install @babel/cli or @babel/core.) In the case one of your dependencies is installing babel and you cannot uninstall it yourself, use the complete name of the loader in the webpack config:

  {
    test: /\.m?js$/,
    loader: 'babel-loader',
  }

Customize config based on webpack target

Webpack supports bundling multiple targets. For cases where you may want different Babel configurations for each target (like web and node), this loader provides a target property via Babel's caller API.

For example, to change the environment targets passed to @babel/preset-env based on the webpack target:

// babel.config.js

module.exports = api => {
  return {
    plugins: [
      "@babel/plugin-proposal-nullish-coalescing-operator",
      "@babel/plugin-proposal-optional-chaining"
    ],
    presets: [
      [
        "@babel/preset-env",
        {
          useBuiltIns: "entry",
          // caller.target will be the same as the target option from webpack
          targets: api.caller(caller => caller && caller.target === "node")
            ? { node: "current" }
            : { chrome: "58", ie: "11" }
        }
      ]
    ]
  }
}

Customized Loader

babel-loader exposes a loader-builder utility that allows users to add custom handling of Babel's configuration for each file that it processes.

.custom accepts a callback that will be called with the loader's instance of babel so that tooling can ensure that it using exactly the same @babel/core instance as the loader itself.

In cases where you want to customize without actually having a file to call .custom, you may also pass the customize option with a string pointing at a file that exports your custom callback function.

Example

// Export from "./my-custom-loader.js" or whatever you want.
module.exports = require("babel-loader").custom(babel => {
  function myPlugin() {
    return {
      visitor: {},
    };
  }

  return {
    // Passed the loader options.
    customOptions({ opt1, opt2, ...loader }) {
      return {
        // Pull out any custom options that the loader might have.
        custom: { opt1, opt2 },

        // Pass the options back with the two custom options removed.
        loader,
      };
    },

    // Passed Babel's 'PartialConfig' object.
    config(cfg) {
      if (cfg.hasFilesystemConfig()) {
        // Use the normal config
        return cfg.options;
      }

      return {
        ...cfg.options,
        plugins: [
          ...(cfg.options.plugins || []),

          // Include a custom plugin in the options.
          myPlugin,
        ],
      };
    },

    result(result) {
      return {
        ...result,
        code: result.code + "\n// Generated by some custom loader",
      };
    },
  };
});

// And in your Webpack config
module.exports = {
  // ..
  module: {
    rules: [{
      // ...
      loader: path.join(__dirname, 'my-custom-loader.js'),
      // ...
    }]
  }
};

`customOptions(options: Object): { custom: Object, loader: Object }`

Given the loader's options, split custom options out of babel-loader's options.

`config(cfg: PartialConfig): Object`

Given Babel's PartialConfig object, return the options object that should be passed to babel.transform.

`result(result: Result): Result`

Given Babel's result object, allow loaders to make additional tweaks to it.

License

MIT

bundle-loader

Bundle loader for webpack

Install

npm i bundle-loader --save

Usage

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.bundle\.js$/,
        use: 'bundle-loader'
      }
    ]
  }
}

The chunk is requested, when you require the bundle.

file.js

import bundle from './file.bundle.js';

To wait until the chunk is available (and get the exports) you need to async wait for it.

bundle((file) => {
  // use the file like it was required
  const file = require('./file.js')
});

This wraps the require('file.js') in a require.ensure block

Multiple callbacks can be added. They will be executed in the order of addition.

bundle(callbackTwo)
bundle(callbackThree)

If a callback is added after dependencies were loaded, it will be called immediately.

Options

Name	Type	Default	Description
Name Type Default Description `lazy` `{Boolean}`	`{Boolean}`	`false`	Loads the imported bundle asynchronously
Name Type Default Description `name` `{String}`	`{String}`	`[id].[name]`	Configure a custom filename for your imported bundle

`lazy`

The file is requested when you require the bundle-loader. If you want it to request it lazy, use:

webpack.config.js

{
  loader: 'bundle-loader',
  options: {
    lazy: true
  }
}

import bundle from './file.bundle.js'

bundle((file) => {...})

ℹ️ The chunk is not requested until you call the load function

`name`

You may set name for a bundle using the name options parameter. See documentation.

webpack.config.js

{
  loader: 'bundle-loader',
  options: {
    name: '[name]'
  }
}

:warning: chunks created by the loader will be named according to the output.chunkFilename rule, which defaults to [id].[name]. Here [name] corresponds to the chunk name set in the name options parameter.

Examples

import bundle from './file.bundle.js'

webpack.config.js

module.exports = {
  entry: {
   index: './App.js'
  },
  output: {
    path: path.resolve(__dirname, 'dest'),
    filename: '[name].js',
    // or whatever other format you want
    chunkFilename: '[name].[id].js',
  },
  module: {
    rules: [
      {
        test: /\.bundle\.js$/,
        use: {
          loader: 'bundle-loader',
          options: {
            name: 'my-chunk'
          }
        }
      }
    ]
  }
}

Normal chunks will show up using the filename rule above, and be named according to their [chunkname].

Chunks from bundle-loader, however will load using the chunkFilename rule, so the example files will produce my-chunk.1.js and file-2.js respectively.

You can also use chunkFilename to add hash values to the filename, since putting [hash] in the bundle options parameter does not work correctly.

Maintainers

Juho Vepsäläinen

Joshua Wiens

Michael Ciniawsky

Alexander Krasnoyarov

cache-loader

The cache-loader allow to Caches the result of following loaders on disk (default) or in the database.

Getting Started

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

npm install --save-dev cache-loader

Add this loader in front of other (expensive) loaders to cache the result on disk.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.ext$/,
        use: ['cache-loader', ...loaders],
        include: path.resolve('src'),
      },
    ],
  },
};

⚠️ Note that there is an overhead for saving the reading and saving the cache file, so only use this loader to cache expensive loaders.

Options

Name	Type	n Default	Description
Name Type n Default Description `cacheContext` `{String}`	`{String}`	`undefined`	Allows you to override the default cache context in order to generate the cache relatively to a path. By default it will use absolute paths
Name Type n Default Description `cacheKey` `{Function(options, request) -> {String}}`	`{Function(options, request) -> {String}}`	`undefined`	Allows you to override default cache key generator
Name Type n Default Description `cacheDirectory` `{String}`	`{String}`	`findCacheDir({ name: 'cache-loader' }) or os.tmpdir()`	Provide a cache directory where cache items should be stored (used for default read/write implementation)
Name Type n Default Description `cacheIdentifier` `{String}`	`{String}`	`cache-loader:{version} {process.env.NODE_ENV}`	Provide an invalidation identifier which is used to generate the hashes. You can use it for extra dependencies of loaders (used for default read/write implementation)
Name Type n Default Description `compare` `{Function(stats, dep) -> {Boolean}}`	`{Function(stats, dep) -> {Boolean}}`	`undefined`	Allows you to override default comparison function between the cached dependency and the one is being read. Return `true` to use the cached resource
Name Type n Default Description `precision` `{Number}`	`{Number}`	`0`	Round `mtime` by this number of milliseconds both for `stats` and `dep` before passing those params to the comparing function
Name Type n Default Description `read` `{Function(cacheKey, callback) -> {void}}`	`{Function(cacheKey, callback) -> {void}}`	`undefined`	Allows you to override default read cache data from file
Name Type n Default Description `readOnly` `{Boolean}`	`{Boolean}`	`false`	Allows you to override default value and make the cache read only (useful for some environments where you don't want the cache to be updated, only read from it)
Name Type n Default Description `write` `{Function(cacheKey, data, callback) -> {void}}`	`{Function(cacheKey, data, callback) -> {void}}`	`undefined`	Allows you to override default write cache data to file (e.g. Redis, memcached)

Examples

Basic

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: ['cache-loader', 'babel-loader'],
        include: path.resolve('src'),
      },
    ],
  },
};

Database Integration

webpack.config.js

// Or different database client - memcached, mongodb, ...
const redis = require('redis');
const crypto = require('crypto');

// ...
// connect to client
// ...

const BUILD_CACHE_TIMEOUT = 24 * 3600; // 1 day

function digest(str) {
  return crypto
    .createHash('md5')
    .update(str)
    .digest('hex');
}

// Generate own cache key
function cacheKey(options, request) {
  return `build:cache:${digest(request)}`;
}

// Read data from database and parse them
function read(key, callback) {
  client.get(key, (err, result) => {
    if (err) {
      return callback(err);
    }

    if (!result) {
      return callback(new Error(`Key ${key} not found`));
    }

    try {
      let data = JSON.parse(result);
      callback(null, data);
    } catch (e) {
      callback(e);
    }
  });
}

// Write data to database under cacheKey
function write(key, data, callback) {
  client.set(key, JSON.stringify(data), 'EX', BUILD_CACHE_TIMEOUT, callback);
}

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: [
          {
            loader: 'cache-loader',
            options: {
              cacheKey,
              read,
              write,
            },
          },
          'babel-loader',
        ],
        include: path.resolve('src'),
      },
    ],
  },
};

Contributing

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

CONTRIBUTING

License

MIT

coffee-loader

Loads CoffeeScript like JavaScript

Install

npm install --save-dev coffee-loader

Usage

import coffee from 'coffee-loader!./file.coffee';

`Configuration (recommended)`

import coffee from 'file.coffee';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.coffee$/,
        use: [ 'coffee-loader' ]
      }
    ]
  }
}

Options

Name	Default	Description
Name Default Description `literate` `false`	`false`	Enable CoffeeScript in Markdown (Code Blocks) e.g `file.coffee.md`
Name Default Description `transpile` `false`	`false`	Provide Babel presets and plugins

`Literate`

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.coffee.md$/,
        use: [
          {
            loader: 'coffee-loader',
            options: { literate: true }
          }
        ]
      }
    ]
  }
}

`Sourcemaps`

Source maps are always produced.

`Transpile`

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.coffee$/,
        use: [
          {
            loader: 'coffee-loader',
            options: { 
              transpile: {
                presets: ['env']
              }
            }
          }
        ]
      }
    ]
  }
}

Maintainer

Juho Vepsäläinen

Joshua Wiens

Kees Kluskens

Sean Larkin

coffee-redux-loader

Coffee Script Redux loader for Webpack.

Install

npm i -D coffee-redux-loader

Usage

var exportsOfFile = require("coffee-redux-loader!./file.coffee");
// => return exports of executed and compiled file.coffee

Don't forget to polyfill require if you want to use it in node. See webpack documentation.

Maintainers

Juho Vepsäläinen

Joshua Wiens

Kees Kluskens

Sean Larkin

coverjs-loader

Usage

webpack-dev-server "mocha!./cover-my-client-tests.js" --options webpackOptions.js

// webpackOptions.js
module.exports = {
	// your webpack options
	output: "bundle.js",
	publicPrefix: "/",
	debug: true,
	includeFilenames: true,
	watch: true,

	// the coverjs loader binding
	postLoaders: [{
		test: "", // every file
		exclude: [
			"node_modules.chai",
			"node_modules.coverjs-loader",
			"node_modules.webpack.buildin"
		],
		loader: "coverjs-loader"
	}]
}

// cover-my-client-tests.js
require("./my-client-tests");

after(function() {
	require("cover-loader").reportHtml();
});

See the-big-test for an example.

You don't have to combine it with the mocha loader, it's independent. So if you want to cover a normal app usage, you can do so. The reportHtml function just appends the output to the body.

License

MIT (http://www.opensource.org/licenses/mit-license.php)

css-loader

The css-loader interprets @import and url() like import/require() and will resolve them.

Getting Started

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

npm install --save-dev css-loader

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

file.js

import css from 'file.css';

webpack.config.js

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

Good loaders for requiring your assets are the file-loader and the url-loader which you should specify in your config (see below).

And run webpack via your preferred method.

`toString`

You can also use the css-loader results directly as a string, such as in Angular's component style.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['to-string-loader', 'css-loader'],
      },
    ],
  },
};

const css = require('./test.css').toString();

console.log(css); // {String}

If there are SourceMaps, they will also be included in the result string.

If, for one reason or another, you need to extract CSS as a plain string resource (i.e. not wrapped in a JS module) you might want to check out the extract-loader. It's useful when you, for instance, need to post process the CSS as a string.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'handlebars-loader', // handlebars loader expects raw resource string
          'extract-loader',
          'css-loader',
        ],
      },
    ],
  },
};

Options

Name	Type	Default	Description
Name Type Default Description `url` `{Boolean\\|Function}`	`{Boolean\\|Function}`	`true`	Enables/Disables `url` / `image-set` functions handling
Name Type Default Description `import` `{Boolean\\|Function}`	`{Boolean\\|Function}`	`true`	Enables/Disables `@import` at-rules handling
Name Type Default Description `modules` `{Boolean\\|String\\|Object}`	`{Boolean\\|String\\|Object}`	`false`	Enables/Disables CSS Modules and their configuration
Name Type Default Description `sourceMap` `{Boolean}`	`{Boolean}`	`false`	Enables/Disables generation of source maps
Name Type Default Description `importLoaders` `{Number}`	`{Number}`	`0`	Enables/Disables or setups number of loaders applied before CSS loader
Name Type Default Description `localsConvention` `{String}`	`{String}`	`'asIs'`	Style of exported classnames
Name Type Default Description `onlyLocals` `{Boolean}`	`{Boolean}`	`false`	Export only locals
Name Type Default Description `esModule` `{Boolean}`	`{Boolean}`	`false`	Use ES modules syntax

`url`

Type: Boolean|Function Default: true

Enables/Disables url/image-set functions handling. Control url() resolving. Absolute URLs and root-relative URLs are not resolving.

Examples resolutions:

url(image.png) => require('./image.png')
url('image.png') => require('./image.png')
url(./image.png) => require('./image.png')
url('./image.png') => require('./image.png')
url('http://dontwritehorriblecode.com/2112.png') => require('http://dontwritehorriblecode.com/2112.png')
image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.png') and require('./image2x.png')

To import assets from a node_modules path (include resolve.modules) and for alias, prefix it with a ~:

url(~module/image.png) => require('module/image.png')
url('~module/image.png') => require('module/image.png')
url(~aliasDirectory/image.png) => require('otherDirectory/image.png')

`Boolean`

Enable/disable url() resolving.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          url: true,
        },
      },
    ],
  },
};

`Function`

Allow to filter url(). All filtered url() will not be resolved (left in the code as they were written).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          url: (url, resourcePath) => {
            // resourcePath - path to css file

            // Don't handle `img.png` urls
            if (url.includes('img.png')) {
              return false;
            }

            return true;
          },
        },
      },
    ],
  },
};

`import`

Type: Boolean|Function Default: true

Enables/Disables @import at-rules handling. Control @import resolving. Absolute urls in @import will be moved in runtime code.

Examples resolutions:

@import 'style.css' => require('./style.css')
@import url(style.css) => require('./style.css')
@import url('style.css') => require('./style.css')
@import './style.css' => require('./style.css')
@import url(./style.css) => require('./style.css')
@import url('./style.css') => require('./style.css')
@import url('http://dontwritehorriblecode.com/style.css') => @import url('http://dontwritehorriblecode.com/style.css') in runtime

To import styles from a node_modules path (include resolve.modules) and for alias, prefix it with a ~:

@import url(~module/style.css) => require('module/style.css')
@import url('~module/style.css') => require('module/style.css')
@import url(~aliasDirectory/style.css) => require('otherDirectory/style.css')

`Boolean`

Enable/disable @import resolving.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          import: true,
        },
      },
    ],
  },
};

`Function`

Allow to filter @import. All filtered @import will not be resolved (left in the code as they were written).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          import: (parsedImport, resourcePath) => {
            // parsedImport.url - url of `@import`
            // parsedImport.media - media query of `@import`
            // resourcePath - path to css file

            // Don't handle `style.css` import
            if (parsedImport.url.includes('style.css')) {
              return false;
            }

            return true;
          },
        },
      },
    ],
  },
};

`modules`

Type: Boolean|String|Object Default: false

Enables/Disables CSS Modules and their configuration.

The modules option enables/disables the CSS Modules specification and setup basic behaviour.

Using false value increase performance because we avoid parsing CSS Modules features, it will be useful for developers who use vanilla css or use other technologies.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: true,
        },
      },
    ],
  },
};

`Features`

`Scope`

Using local value requires you to specify :global classes. Using global value requires you to specify :local classes. Using pure value requires selectors must contain at least one local class or id.

You can find more information here.

Styles can be locally scoped to avoid globally scoping styles.

The syntax :local(.className) can be used to declare className in the local scope. The local identifiers are exported by the module.

With :local (without brackets) local mode can be switched on for this selector. The :global(.className) notation can be used to declare an explicit global selector. With :global (without brackets) global mode can be switched on for this selector.

The loader replaces local selectors with unique identifiers. The chosen unique identifiers are exported by the module.

:local(.className) {
  background: red;
}
:local .className {
  color: green;
}
:local(.className .subClass) {
  color: green;
}
:local .className .subClass :global(.global-class-name) {
  color: blue;
}

._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
}
._23_aKvs-b8bW2Vg3fwHozO {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name {
  color: blue;
}

ℹ️ Identifiers are exported

exports.locals = {
  className: '_23_aKvs-b8bW2Vg3fwHozO',
  subClass: '_13LGdX8RMStbBE9w-t0gZ1',
};

CamelCase is recommended for local selectors. They are easier to use within the imported JS module.

You can use :local(#someId), but this is not recommended. Use classes instead of ids.

`Composing`

When declaring a local classname you can compose a local class from another local classname.

:local(.className) {
  background: red;
  color: yellow;
}

:local(.subClass) {
  composes: className;
  background: blue;
}

This doesn't result in any change to the CSS itself but exports multiple classnames.

exports.locals = {
  className: '_23_aKvs-b8bW2Vg3fwHozO',
  subClass: '_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO',
};

._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
  color: yellow;
}

._13LGdX8RMStbBE9w-t0gZ1 {
  background: blue;
}

`Importing`

To import a local classname from another module.

:local(.continueButton) {
  composes: button from 'library/button.css';
  background: red;
}

:local(.nameEdit) {
  composes: edit highlight from './edit.css';
  background: red;
}

To import from multiple modules use multiple composes: rules.

:local(.className) {
  composes: edit hightlight from './edit.css';
  composes: button from 'module/button.css';
  composes: classFromThisModule;
  background: red;
}

`Values`

You can use @value to specific values to be reused throughout a document.

We recommend use prefix v- for values, s- for selectors and m- for media at-rules.

@value v-primary: #BF4040;
@value s-black: black-selector;
@value m-large: (min-width: 960px);

.header {
  color: v-primary;
  padding: 0 10px;
}

.s-black {
  color: black;
}

@media m-large {
  .header {
    padding: 0 20px;
  }
}

`Boolean`

Enable CSS Modules features.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: true,
        },
      },
    ],
  },
};

`String`

Enable CSS Modules features and setup mode.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          // Using `local` value has same effect like using `modules: true`
          modules: 'global',
        },
      },
    ],
  },
};

`Object`

Enable CSS Modules features and setup options for them.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            mode: 'local',
            exportGlobals: true,
            localIdentName: '[path][name]__[local]--[hash:base64:5]',
            context: path.resolve(__dirname, 'src'),
            hashPrefix: 'my-custom-hash',
          },
        },
      },
    ],
  },
};

`auto`

Type: Boolean|RegExp Default: 'undefined'

Allows auto enable css modules based on filename.

`Boolean`

Possible values:

true - enable css modules for all files for which /\.module\.\w+$/i.test(filename) return true
false - disable css modules

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            auto: true,
          },
        },
      },
    ],
  },
};

`RegExp`

Enable css modules for files based on a filename and satisfying your regex.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            auto: /\.custom-module\.\w+$/i,
          },
        },
      },
    ],
  },
};

`mode`

Type: String|Function Default: 'local'

Setup mode option. You can omit the value when you want local mode.

`String`

Possible values - local, global, and pure.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            mode: 'global',
          },
        },
      },
    ],
  },
};

`Function`

Allows set different values for the mode option based on a filename

Possible return values - local, global, and pure.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            // Callback must return "local", "global", or "pure" values
            mode: (resourcePath) => {
              if (/pure.css$/i.test(resourcePath)) {
                return 'pure';
              }

              if (/global.css$/i.test(resourcePath)) {
                return 'global';
              }

              return 'local';
            },
          },
        },
      },
    ],
  },
};

`exportGlobals`

Type: Boolean Default: false

Allow css-loader to export names from global class or id, so you can use that as local name.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            exportGlobals: true,
          },
        },
      },
    ],
  },
};

`localIdentName`

Type: String Default: '[hash:base64]'

You can configure the generated ident with the localIdentName query parameter. See loader-utils's documentation for more information on options.

Recommendations:

use '[path][name]__[local]' for development
use '[hash:base64]' for production

The [local] placeholder contains original class.

Note: all reserved (<>:"/\|?*) and control filesystem characters (excluding characters in the [local] placeholder) will be converted to -.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            localIdentName: '[path][name]__[local]--[hash:base64:5]',
          },
        },
      },
    ],
  },
};

`context`

Type: String Default: undefined

Allow to redefine basic loader context for local ident name. By default we use rootContext of loader.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            context: path.resolve(__dirname, 'context'),
          },
        },
      },
    ],
  },
};

`hashPrefix`

Type: String Default: undefined

Allow to add custom hash to generate more unique classes.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            hashPrefix: 'hash',
          },
        },
      },
    ],
  },
};

`getLocalIdent`

Type: Function Default: undefined

You can also specify the absolute path to your custom getLocalIdent function to generate classname based on a different schema. By default we use built-in function to generate a classname.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            getLocalIdent: (context, localIdentName, localName, options) => {
              return 'whatever_random_class_name';
            },
          },
        },
      },
    ],
  },
};

`localIdentRegExp`

Type: String|RegExp Default: undefined

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          modules: {
            localIdentRegExp: /page-(.*)\.css/i,
          },
        },
      },
    ],
  },
};

`sourceMap`

Type: Boolean Default: false

Enables/Disables generation of source maps.

To include source maps set the sourceMap option.

They are not enabled by default because they expose a runtime overhead and increase in bundle size (JS source maps do not).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          sourceMap: true,
        },
      },
    ],
  },
};

`importLoaders`

Type: Number Default: 0

Enables/Disables or setups number of loaders applied before CSS loader.

The option importLoaders allows you to configure how many loaders before css-loader should be applied to @imported resources.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              importLoaders: 2,
              // 0 => no loaders (default);
              // 1 => postcss-loader;
              // 2 => postcss-loader, sass-loader
            },
          },
          'postcss-loader',
          'sass-loader',
        ],
      },
    ],
  },
};

This may change in the future when the module system (i. e. webpack) supports loader matching by origin.

`localsConvention`

Type: String Default: 'asIs'

Style of exported classnames.

By default, the exported JSON keys mirror the class names (i.e asIs value).

Name	Type	Description
Name Type Description `'asIs'` `{String}`	`{String}`	Class names will be exported as is.
Name Type Description `'camelCase'` `{String}`	`{String}`	Class names will be camelized, the original class name will not to be removed from the locals
Name Type Description `'camelCaseOnly'` `{String}`	`{String}`	Class names will be camelized, the original class name will be removed from the locals
Name Type Description `'dashes'` `{String}`	`{String}`	Only dashes in class names will be camelized
Name Type Description `'dashesOnly'` `{String}`	`{String}`	Dashes in class names will be camelized, the original class name will be removed from the locals

file.css

.class-name {
}

file.js

import { className } from 'file.css';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          localsConvention: 'camelCase',
        },
      },
    ],
  },
};

`onlyLocals`

Type: Boolean Default: false

Export only locals.

Useful when you use css modules for pre-rendering (for example SSR). For pre-rendering with mini-css-extract-plugin you should use this option instead of style-loader!css-loader in the pre-rendering bundle. It doesn't embed CSS but only exports the identifier mappings.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        options: {
          onlyLocals: true,
        },
      },
    ],
  },
};

`esModule`

Type: Boolean Default: false

By default, css-loader generates JS modules that use the CommonJS 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 ES module syntax using:

webpack.config.js

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

Examples

Assets

The following webpack.config.js can load CSS files, embed small PNG/JPG/GIF/SVG images as well as fonts as Data URLs and copy larger files to the output directory.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        loader: 'url-loader',
        options: {
          limit: 8192,
        },
      },
    ],
  },
};

Extract

For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.

This can be achieved by using the mini-css-extract-plugin to extract the CSS when running in production mode.
As an alternative, if seeking better development performance and css outputs that mimic production. extract-css-chunks-webpack-plugin offers a hot module reload friendly, extended version of mini-css-extract-plugin. HMR real CSS files in dev, works like mini-css in non-dev

Pure CSS, CSS modules and PostCSS

When you have pure CSS (without CSS modules), CSS modules and PostCSS in your project you can use this setup:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        // For CSS modules
        // For pure CSS - /\.css$/i,
        // For Sass/SCSS - /\.((c|sa|sc)ss)$/i,
        // For Less - /\.((c|le)ss)$/i,
        test: /\.((c|sa|sc)ss)$/i,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              // Run `postcss-loader` on each CSS `@import`, do not forget that `sass-loader` compile non CSS `@import`'s into a single file
              // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
              importLoaders: 1,
              // Automatically enable css modules for files satisfying `/\.module\.\w+$/i` RegExp.
              modules: { auto: true },
            },
          },
          {
            loader: 'postcss-loader',
            options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
          },
          // Can be `less-loader`
          // The `test` property should be `\.less/i`
          {
            test: /\.s[ac]ss$/i,
            loader: 'sass-loader',
          },
        ],
      },
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        loader: 'url-loader',
        options: {
          limit: 8192,
        },
      },
    ],
  },
};

Contributing

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

CONTRIBUTING

License

MIT

eslint-loader

A ESlint loader for webpack

Install

npm install eslint-loader --save-dev

Note: You also need to install eslint from npm, if you haven't already:

npm install eslint --save-dev

Usage

In your webpack configuration:

module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          // eslint options (if necessary)
        },
      },
    ],
  },
  // ...
};

When using with transpiling loaders (like babel-loader), make sure they are in correct order (bottom to top). Otherwise files will be checked after being processed by babel-loader:

module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: ['babel-loader', 'eslint-loader'],
      },
    ],
  },
  // ...
};

To be safe, you can use enforce: 'pre' section to check source files, not modified by other loaders (like babel-loader):

module.exports = {
  // ...
  module: {
    rules: [
      {
        enforce: 'pre',
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
      },
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'babel-loader',
      },
    ],
  },
  // ...
};

Options

You can pass eslint options using standard webpack loader options.

Note: That the config option you provide will be passed to the CLIEngine. This is a different set of options than what you'd specify in package.json or .eslintrc. See the eslint docs for more detail.

`cache`

Type: Boolean|String
Default: false

This option will enable caching of the linting results into a file. This is particularly useful in reducing linting time when doing a full build.

This can either be a boolean value or the cache directory path(ex: './.eslint-loader-cache').

If cache: true is used, the cache is written to the ./node_modules/.cache/eslint-loader directory. This is the recommended usage.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          cache: true,
        },
      },
    ],
  },
};

`eslintPath`

Type: String
Default: eslint

Path to eslint instance that will be used for linting. If the eslintPath is a folder like a official eslint, or specify a formatter option. Now you dont have to install eslint.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          eslintPath: path.join(__dirname, 'reusable-eslint'),
        },
      },
    ],
  },
};

`fix`

Type: Boolean
Default: false

This option will enable ESLint autofix feature.

Be careful: this option will change source files.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          fix: true,
        },
      },
    ],
  },
};

`formatter`

Type: String|Function
Default: stylish

This option accepts a function that will have one argument: an array of eslint messages (object). The function must return the output as a string. You can use official eslint formatters.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          // several examples !

          // default value
          formatter: 'stylish',

          // community formatter
          formatter: require('eslint-friendly-formatter'),

          // custom formatter
          formatter: function (results) {
            // `results` format is available here
            // http://eslint.org/docs/developer-guide/nodejs-api.html#executeonfiles()

            // you should return a string
            // DO NOT USE console.*() directly !
            return 'OUTPUT';
          },
        },
      },
    ],
  },
};

Errors and Warning

By default the loader will auto adjust error reporting depending on eslint errors/warnings counts. You can still force this behavior by using emitError or emitWarning options:

`emitError`

Type: Boolean
Default: false

Will always return errors, if this option is set to true.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          emitError: true,
        },
      },
    ],
  },
};

`emitWarning`

Type: Boolean
Default: false

Will always return warnings, if option is set to true. If you're using hot module replacement, you may wish to enable this in development, or else updates will be skipped when there's an eslint error.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          emitWarning: true,
        },
      },
    ],
  },
};

`failOnError`

Type: Boolean
Default: false

Will cause the module build to fail if there are any errors, if option is set to true.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          failOnError: true,
        },
      },
    ],
  },
};

`failOnWarning`

Type: Boolean
Default: false

Will cause the module build to fail if there are any warnings, if option is set to true.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          failOnWarning: true,
        },
      },
    ],
  },
};

`quiet`

Type: Boolean
Default: false

Will process and report errors only and ignore warnings, if this option is set to true.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          quiet: true,
        },
      },
    ],
  },
};

`outputReport`

Type: Boolean|Object
Default: false

Write the output of the errors to a file, for example a checkstyle xml file for use for reporting on Jenkins CI.

The filePath is an absolute path or relative to the webpack config: output.path. You can pass in a different formatter for the output file, if none is passed in the default/configured formatter will be used.

module.exports = {
  entry: '...',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'eslint-loader',
        options: {
          outputReport: {
            filePath: 'checkstyle.xml',
            formatter: 'checkstyle',
          },
        },
      },
    ],
  },
};

Gotchas

NoEmitOnErrorsPlugin

NoEmitOnErrorsPlugin is now automatically enabled in webpack 4, when mode is either unset, or set to production. So even ESLint warnings will fail the build. No matter what error settings are used for eslint-loader, except if emitWarning enabled.

Defining `configFile` or using `eslint -c path/.eslintrc`

Bear in mind that when you define configFile, eslint doesn't automatically look for .eslintrc files in the directory of the file to be linted. More information is available in official eslint documentation in section Using Configuration Files. See #129.

Changelog

License

MIT

exports-loader

exports loader module for webpack

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install exports-loader --save-dev

Then add the loader to the desired require calls. For example:

require('exports-loader?file,parse=helpers.parse!./file.js');
// adds the following code to the file's source:
//  exports['file'] = file;
//  exports['parse'] = helpers.parse;

require('exports-loader?file!./file.js');
// adds the following code to the file's source:
//  module.exports = file;

require('exports-loader?[name]!./file.js');
// adds the following code to the file's source:
//  module.exports = file;

And run webpack via your preferred method.

Contributing

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

CONTRIBUTING

License

MIT

expose-loader

expose loader module for webpack

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install expose-loader --save-dev

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

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /.js/,
        use: [
          {
            loader: `expose-loader`,
            options: {...options}
          }
        ]
      }
    ]
  }
}

And then require the target file in your bundle's code:

// src/entry.js
require("expose-loader?libraryName!./thing.js");

And run webpack via your preferred method.

Examples

For example, let's say you want to expose jQuery as a global called $:

require("expose-loader?$!jquery");

Thus, window.$ is then available in the browser console.

Alternately, you can set this in your config file:

// webpack.config.js
module: {
  rules: [{
    test: require.resolve('jquery'),
    use: [{
      loader: 'expose-loader',
      options: '$'
    }]
  }]
}

Let's say you also want to expose it as window.jQuery in addition to window.$. For multiple expose you can use ! in loader string:

// webpack.config.js
module: {
  rules: [{
    test: require.resolve('jquery'),
    use: [{
      loader: 'expose-loader',
      options: 'jQuery'
    },{
      loader: 'expose-loader',
      options: '$'
    }]
  }]
}

The require.resolve call is a Node.js function (unrelated to require.resolve in webpack processing). require.resolve gives you the absolute path to the module ("/.../app/node_modules/react/react.js"). So the expose only applies to the react module. And it's only exposed when used in the bundle.

Contributing

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

CONTRIBUTING

License

MIT

extract-loader

webpack loader to extract HTML and CSS from the bundle.

The extract-loader evaluates the given source code on the fly and returns the result as string. Its main use-case is to resolve urls within HTML and CSS coming from their respective loaders. Use the file-loader to emit the extract-loader's result as separate file.

import stylesheetUrl from "file-loader!extract-loader!css-loader!main.css";
// stylesheetUrl will now be the hashed url to the final stylesheet

The extract-loader works similar to the extract-text-webpack-plugin and the mini-css-extract-plugin and is meant as a lean alternative to it. When evaluating the source code, it provides a fake context which was especially designed to cope with the code generated by the html- or the css-loader. Thus it might not work in other situations.

Installation

$ npm install extract-loader --save-dev

Examples

Extracting a main.css

Bundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or hot module replacement in development. In production, on the other hand, it's not a good idea to apply your stylesheets depending on JS execution. Rendering may be delayed or even a FOUC might be visible. Thus it's still better to have them as separate files in your final production build.

With the extract-loader, you are able to reference your main.css as regular entry. The following webpack.config.js shows how to load your styles with the style-loader in development and as separate file in production.

module.exports = ({ mode }) => {
    const pathToMainCss = require.resolve("./app/main.css");
    const loaders = [{
        loader: "css-loader",
        options: {
            sourceMap: true
        }
    }];

    if (mode === "production") {
        loaders.unshift(
            "file-loader",
            "extract-loader"
        );
    } else {
        loaders.unshift("style-loader");
    }

    return {
        mode,
        entry: pathToMainCss,
        module: {
            rules: [
                {
                    test: pathToMainCss,
                    loaders: loaders
                },
            ]
        }
    };
};

Extracting the index.html

You can even add your index.html as entry and reference your stylesheets from there. In that case, tell the html-loader to also pick up link:href:

module.exports = ({ mode }) => {
    const pathToMainJs = require.resolve("./app/main.js");
    const pathToIndexHtml = require.resolve("./app/index.html");

    return {
        mode,
        entry: [
            pathToMainJs,
            pathToIndexHtml
        ],
        module: {
            rules: [
                {
                    test: pathToIndexHtml,
                    use: [
                        "file-loader",
                        "extract-loader",
                        {
                            loader: "html-loader",
                            options: {
                                attrs: ["img:src", "link:href"]
                            }
                        }
                    ]
                },
                {
                    test: /\.css$/,
                    use: [
                        "file-loader",
                        "extract-loader",
                        {
                            loader: "css-loader",
                            options: {
                                sourceMap: true
                            }
                        }
                    ]
                },
                {
                    test: /\.jpg$/,
                    use: "file-loader"
                }
            ]
        }
    };
}

turns

<html>
<head>
    <link href="main.css" type="text/css" rel="stylesheet">
</head>
<body>
    <img src="hi.jpg">
</body>
</html>

into

<html>
<head>
    <link href="7c57758b88216530ef48069c2a4c685a.css" type="text/css" rel="stylesheet">
</head>
<body>
    <img src="6ac05174ae9b62257ff3aa8be43cf828.jpg">
</body>
</html>

Source Maps

If you want source maps in your extracted CSS files, you need to set the sourceMap option of the css-loader:

    {
        loader: "css-loader",
        options: {
            sourceMap: true
        }
    }

Options

There is currently exactly one option: publicPath. If you are using a relative publicPath in webpack's output options and extracting to a file with the file-loader, you might need this to account for the location of your extracted file. publicPath may be defined as a string or a function that accepts current loader context as single argument.

Example with publicPath option as a string:

module.exports = {
    output: {
        path: path.resolve("./dist"),
        publicPath: "dist/"
    },
    module: {
        rules: [
            {
                test: /\.css$/,
                use: [
                    {
                        loader: "file-loader",
                        options: {
                            name: "assets/[name].[ext]",
                        },
                    },
                    {
                        loader: "extract-loader",
                        options: {
                            publicPath: "../",
                        }
                    },
                    {
                        loader: "css-loader",
                    },
                ],
            }
        ]
    }
};

Example with publicPath option as a function:

module.exports = {
    output: {
        path: path.resolve("./dist"),
        publicPath: "dist/"
    },
    module: {
        rules: [
            {
                test: /\.css$/,
                use: [
                    {
                        loader: "file-loader",
                        options: {
                            name: "assets/[name].[ext]",
                        },
                    },
                    {
                        loader: "extract-loader",
                        options: {
                            // dynamically return a relative publicPath based on how deep in directory structure the loaded file is in /src/ directory
                            publicPath: (context) => '../'.repeat(path.relative(path.resolve('src'), context.context).split('/').length),
                        }
                    },
                    {
                        loader: "css-loader",
                    },
                ],
            }
        ]
    }
};

You need another option? Then you should think about:

Contributing

From opening a bug report to creating a pull request: every contribution is appreciated and welcome. If you're planning to implement a new feature or change the api please create an issue first. This way we can ensure that your precious work is not in vain.

All pull requests should have 100% test coverage (with notable exceptions) and need to pass all tests.

Call npm test to run the unit tests
Call npm run coverage to check the test coverage (using istanbul)

License

Unlicense

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 differntly 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

gzip-loader

gzip loader module for webpack

Enables loading gzipped resources.

Install

npm install --save-dev gzip-loader

Usage

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.gz$/,
        enforce: 'pre',
        use: 'gzip-loader'
      }
    ]
  }
}

bundle.js

require("gzip-loader!./file.js.gz");

Maintainers

Alexander Krasnoyarov

html-loader

Exports HTML as string. HTML is minimized when the compiler demands.

Getting Started

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

npm install --save-dev html-loader

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

file.js

import html from './file.html';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
      },
    ],
  },
};

Options

Name	Type	Default	Description
Name Type Default Description `attributes` `{Boolean\\|Object}`	`{Boolean\\|Object}`	`true`	Enables/Disables attributes handling
Name Type Default Description `preprocessor` `{Function}`	`{Function}`	`undefined`	Allows pre-processing of content before handling
Name Type Default Description `minimize` `{Boolean\\|Object}`	`{Boolean\\|Object}`	`true` in production mode, otherwise `false`	Tell `html-loader` to minimize HTML
Name Type Default Description `esModule` `{Boolean}`	`{Boolean}`	`false`	Use ES modules syntax

`attributes`

Type: Boolean|Object Default: true

By default every loadable attributes (for example - <img src="image.png">) is imported (const img = require('./image.png') or import img from "./image.png""). You may need to specify loaders for images in your configuration (recommended file-loader or url-loader).

Supported tags and attributes:

the src attribute of the audio tag
the src attribute of the embed tag
the src attribute of the img tag
the srcset attribute of the img tag
the src attribute of the input tag
the href attribute of the link tag (only for stylesheets)
the data attribute of the object tag
the src attribute of the script tag
the src attribute of the source tag
the srcset attribute of the source tag
the src attribute of the track tag
the poster attribute of the video tag
the src attribute of the video tag

`Boolean`

The true value enables processing of all default elements and attributes, the false disable processing of all attributes.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          // Disables attributes processing
          attributes: false,
        },
      },
    ],
  },
};

`Object`

Allows you to specify which tags and attributes to process, filter them, filter urls and process sources starts with /. For example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          attributes: {
            list: [
              {
                tag: 'img',
                attribute: 'src',
                type: 'src',
              },
              {
                tag: 'img',
                attribute: 'srcset',
                type: 'srcset',
              },
              {
                tag: 'img',
                attribute: 'data-src',
                type: 'src',
              },
              {
                tag: 'img',
                attribute: 'data-srcset',
                type: 'srcset',
              },
              {
                tag: 'link',
                attribute: 'href',
                type: 'src',
                filter: (tag, attribute, attributes) => {
                  if (!/stylesheet/i.test(attributes.rel)) {
                    return false;
                  }

                  if (
                    attributes.type &&
                    attributes.type.trim().toLowerCase() !== 'text/css'
                  ) {
                    return false;
                  }

                  return true;
                },
              },
              // More attributes
            ],
            urlFilter: (attribute, value, resourcePath) => {
              // The `attribute` argument contains a name of the HTML attribute.
              // The `value` argument contains a value of the HTML attribute.
              // The `resourcePath` argument contains a path to the loaded HTML file.

              if (/example\.pdf$/.test(value)) {
                return false;
              }

              return true;
            },
            root: '.',
          },
        },
      },
    ],
  },
};

`list`

Type: Array Default: https://github.com/webpack-contrib/html-loader#attributes

Allows to setup which tags and attributes to process and how, and the ability to filter some of them.

For example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          attributes: {
            list: [
              {
                // Tag name
                tag: 'img',
                // Attribute name
                attribute: 'src',
                // Type of processing, can be `src` or `scrset`
                type: 'src',
              },
              {
                // Tag name
                tag: 'img',
                // Attribute name
                attribute: 'srcset',
                // Type of processing, can be `src` or `scrset`
                type: 'srcset',
              },
              {
                tag: 'img',
                attribute: 'data-src',
                type: 'src',
              },
              {
                tag: 'img',
                attribute: 'data-srcset',
                type: 'srcset',
              },
              {
                // Tag name
                tag: 'link',
                // Attribute name
                attribute: 'href',
                // Type of processing, can be `src` or `scrset`
                type: 'src',
                // Allow to filter some attributes
                filter: (tag, attribute, attributes, resourcePath) => {
                  // The `tag` argument contains a name of the HTML tag.
                  // The `attribute` argument contains a name of the HTML attribute.
                  // The `attributes` argument contains all attributes of the tag.
                  // The `resourcePath` argument contains a path to the loaded HTML file.

                  if (/my-html\.html$/.test(resourcePath)) {
                    return false;
                  }

                  if (!/stylesheet/i.test(attributes.rel)) {
                    return false;
                  }

                  if (
                    attributes.type &&
                    attributes.type.trim().toLowerCase() !== 'text/css'
                  ) {
                    return false;
                  }

                  return true;
                },
              },
            ],
          },
        },
      },
    ],
  },
};

If the tag name is not specified it will process all the tags.

You can use your custom filter to specify html elements to be processed.

For example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          attributes: {
            list: [
              {
                // Attribute name
                attribute: 'src',
                // Type of processing, can be `src` or `scrset`
                type: 'src',
                // Allow to filter some attributes (optional)
                filter: (tag, attribute, attributes, resourcePath) => {
                  // The `tag` argument contains a name of the HTML tag.
                  // The `attribute` argument contains a name of the HTML attribute.
                  // The `attributes` argument contains all attributes of the tag.
                  // The `resourcePath` argument contains a path to the loaded HTML file.

                  // choose all HTML tags except img tag
                  return tag.toLowerCase() !== 'img';
                },
              },
            ],
          },
        },
      },
    ],
  },
};

`urlFilter`

Type: Function Default: undefined

Allow to filter urls. All filtered urls will not be resolved (left in the code as they were written). All non requestable sources (for example <img src="javascript:void(0)">) do not handle by default.

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          attributes: {
            urlFilter: (attribute, value, resourcePath) => {
              // The `attribute` argument contains a name of the HTML attribute.
              // The `value` argument contains a value of the HTML attribute.
              // The `resourcePath` argument contains a path to the loaded HTML file.

              if (/example\.pdf$/.test(value)) {
                return false;
              }

              return true;
            },
          },
        },
      },
    ],
  },
};

`root`

Type: String Default: undefined

For urls that start with a /, the default behavior is to not translate them. If a root query parameter is set, however, it will be prepended to the url and then translated.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          attributes: {
            root: '.',
          },
        },
      },
    ],
  },
};

`preprocessor`

Type: Function Default: undefined

Allows pre-processing of content before handling.

⚠ You should always return valid HTML

file.hbs

<div>
  <p>{{firstname}} {{lastname}}</p>
  <img src="image.png" alt="alt" />
<div>

`Function`

You can set the preprocessor option as a Function instance.

webpack.config.js

const Handlebars = require('handlebars');

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: 'html-loader',
        options: {
          preprocessor: (content, loaderContext) => {
            let result;

            try {
              result = Handlebars.compile(content)({
                firstname: 'Value',
                lastname: 'OtherValue',
              });
            } catch (error) {
              loaderContext.emitError(error);

              return content;
            }

            return result;
          },
        },
      },
    ],
  },
};

You can also set the preprocessor option as an asynchronous function instance.

For example:

webpack.config.js

const Handlebars = require('handlebars');

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: 'html-loader',
        options: {
          preprocessor: async (content, loaderContext) => {
            let result;

            try {
              result = await Handlebars.compile(content)({
                firstname: 'Value',
                lastname: 'OtherValue',
              });
            } catch (error) {
              await loaderContext.emitError(error);

              return content;
            }

            return result;
          },
        },
      },
    ],
  },
};

`minimize`

Type: Boolean|Object Default: true in production mode, otherwise false

Tell html-loader to minimize HTML.

`Boolean`

The enabled rules for minimizing by default are the following ones:

collapseWhitespace
conservativeCollapse
keepClosingSlash
minifyCSS
minifyJS
removeAttributeQuotes
removeComments
removeScriptTypeAttributes
removeStyleTypeAttributes
useShortDoctype

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          minimize: true,
        },
      },
    ],
  },
};

`Object`

webpack.config.js

See html-minifier-terser's documentation for more information on the available options.

The rules can be disabled using the following options in your webpack.conf.js

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          minimize: {
            removeComments: false,
            collapseWhitespace: false,
          },
        },
      },
    ],
  },
};

`esModule`

Type: Boolean Default: false

By default, html-loader generates JS modules that use the CommonJS 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 ES module syntax using:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          esModule: true,
        },
      },
    ],
  },
};

Examples

CDN

webpack.config.js

module.exports = {
  module: {
    rules: [
      { test: /\.jpg$/, loader: 'file-loader' },
      { test: /\.png$/, loader: 'url-loader' },
    ],
  },
  output: {
    publicPath: 'http://cdn.example.com/[hash]/',
  },
};

file.html

<img src="image.jpg" data-src="image2x.png" />

index.js

require('html-loader!./file.html');

// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="image2x.png">'

require('html-loader?{"attributes":{"list":[{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');

// => '<img src="image.jpg" data-src="data:image/png;base64,..." >'

require('html-loader?{"attributes":{"list":[{"tag":"img","attribute":"src","type":"src"},{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');

// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="data:image/png;base64,..." >'

require('html-loader?-attributes!./file.html');

// => '<img src="image.jpg"  data-src="image2x.png" >'

:warning: -attributes sets attributes: false.

Process `script` and `link` tags

script.file.js

console.log(document);

style.file.css

a {
  color: red;
}

file.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Title of the document</title>
    <link rel="stylesheet" type="text/css" href="./style.file.css" />
  </head>
  <body>
    Content of the document......
    <script src="./script.file.js"></script>
  </body>
</html>

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        use: ['file-loader?name=[name].[ext]', 'extract-loader', 'html-loader'],
      },
      {
        test: /\.js$/i,
        exclude: /\.file.js$/i,
        loader: 'babel-loader',
      },
      {
        test: /\.file.js$/i,
        loader: 'file-loader',
      },
      {
        test: /\.css$/i,
        exclude: /\.file.css$/i,
        loader: 'css-loader',
      },
      {
        test: /\.file.css$/i,
        loader: 'file-loader',
      },
    ],
  },
};

'Root-relative' URLs

With the same configuration as in the CDN example:

file.html

<img src="/image.jpg" />

scripts.js

require('html-loader!./file.html');

// => '<img src="/image.jpg">'

other-scripts.js

require('html-loader?{"attributes":{"root":"."}}!./file.html');

// => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg">'

Templating

You can use any template system. Below is an example for handlebars.

file.hbs

<div>
  <p>{{firstname}} {{lastname}}</p>
  <img src="image.png" alt="alt" />
<div>

webpack.config.js

const Handlebars = require('handlebars');

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: 'html-loader',
        options: {
          preprocessor: (content, loaderContext) => {
            let result;

            try {
              result = Handlebars.compile(content)({
                firstname: 'Value',
                lastname: 'OtherValue',
              });
            } catch (error) {
              loaderContext.emitError(error);

              return content;
            }

            return result;
          },
        },
      },
    ],
  },
};

PostHTML

You can use PostHTML without any additional loaders.

file.html

<img src="image.jpg" />

webpack.config.js

const posthtml = require('posthtml');
const posthtmlWebp = require('posthtml-webp');

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/i,
        loader: 'html-loader',
        options: {
          preprocessor: (content, loaderContext) => {
            let result;

            try {
              result = posthtml().use(plugin).process(content, { sync: true });
            } catch (error) {
              loaderContext.emitError(error);

              return content;
            }

            return result.html;
          },
        },
      },
    ],
  },
};

Export into HTML files

A very common scenario is exporting the HTML into their own .html file, to serve them directly instead of injecting with javascript. This can be achieved with a combination of 3 loaders:

The html-loader will parse the URLs, require the images and everything you expect. The extract loader will parse the javascript back into a proper html file, ensuring images are required and point to proper path, and the file loader will write the .html file for you. Example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.html$/i,
        use: ['file-loader?name=[name].[ext]', 'extract-loader', 'html-loader'],
      },
    ],
  },
};

Contributing

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

CONTRIBUTING

License

MIT

i18n-loader

Usage

./colors.json

{
	"red": "red",
	"green": "green",
	"blue": "blue"
}

./de-de.colors.json

{
	"red": "rot",
	"green": "gr�n"
}

call it

// assuming our locale is "de-de-berlin"
var locale = require("i18n!./colors.json");

// wait for ready, this is only required once for all locales in a web app
// because all locales of the same language are merged into one chuck
locale(function() {
	console.log(locale.red); // prints rot
	console.log(locale.blue); // prints blue
});

options

You should tell the loader about all your locales, if you want to load them once and than want to use them synchronous.

{
	"i18n": {
		"locales": [
			"de",
			"de-de",
			"fr"
		],
		// "bundleTogether": false
		// this can disable the bundling of locales
	}
}

alternative calls

require("i18n/choose!./file.js"); // chooses the correct file by locale,
					// but it do not merge the objects
require("i18n/concat!./file.js"); // concatinate all fitting locales
require("i18n/merge!./file.js"); // merges the resulting objects
					// ./file.js is excuted while compiling
require("i18n!./file.json") == require("i18n/merge!json!./file.json")

Don't forget to polyfill require if you want to use it in node. See webpack documentation.

License

MIT (http://www.opensource.org/licenses/mit-license.php)

imports-loader

The imports loader allows you to use modules that depend on specific global variables.

This is useful for third-party modules that rely on global variables like $ or this being the window object. The imports loader can add the necessary require('whatever') calls, so those modules work with webpack.

Install

npm install imports-loader

Usage

Given you have this file example.js

$("img").doSomeAwesomeJqueryPluginStuff();

then you can inject the $ variable into the module by configuring the imports-loader like this:

require("imports-loader?$=jquery!./example.js");

This simply prepends var $ = require("jquery"); to example.js.

Syntax

Query value	Equals
Query value Equals `angular` `var angular = require("angular");`	`var angular = require("angular");`
Query value Equals `$=jquery` `var $ = require("jquery");`	`var $ = require("jquery");`
Query value Equals `define=>false` `var define = false;`	`var define = false;`
Query value Equals `config=>{size:50}` `var config = {size:50};`	`var config = {size:50};`
Query value Equals `this=>window` `(function () { ... }).call(window);`	`(function () { ... }).call(window);`

Multiple values

Multiple values are separated by comma ,:

require("imports-loader?$=jquery,angular,config=>{size:50}!./file.js");

webpack.config.js

As always, you should rather configure this in your webpack.config.js:

// ./webpack.config.js

module.exports = {
    ...
    module: {
        rules: [
            {
                test: require.resolve("some-module"),
                use: "imports-loader?this=>window"
            }
        ]
    }
};

Typical Use Cases

jQuery plugins

imports-loader?$=jquery

Custom Angular modules

imports-loader?angular

Disable AMD

There are many modules that check for a define function before using CommonJS. Since webpack is capable of both, they default to AMD in this case, which can be a problem if the implementation is quirky.

Then you can easily disable the AMD path by writing

imports-loader?define=>false

For further hints on compatibility issues, check out Shimming Modules of the official docs.

Maintainers

Juho Vepsäläinen

Joshua Wiens

Kees Kluskens

Sean Larkin

istanbul-instrumenter-loader

Instrument JS files with istanbul-lib-instrument for subsequent code coverage reporting

Install

npm i -D istanbul-instrumenter-loader

Usage

`References`

`Structure`

├─ src
│ |– components
│ | |– bar
│ | │ |─ index.js
│ | |– foo/
│     |– index.js
|– test
| |– src
| | |– components
| | | |– foo
| | | | |– index.js

To create a code coverage report for all components (even for those for which you have no tests yet) you have to require all the 1) sources and 2) tests. Something like it's described in "alternative usage" of karma-webpack

test/index.js

// requires all tests in `project/test/src/components/**/index.js`
const tests = require.context('./src/components/', true, /index\.js$/);

tests.keys().forEach(tests);

// requires all components in `project/src/components/**/index.js`
const components = require.context('../src/components/', true, /index\.js$/);

components.keys().forEach(components);

ℹ️ This file will be the only entry point for karma

karma.conf.js

config.set({
  ...
  files: [
    'test/index.js'
  ],
  preprocessors: {
    'test/index.js': 'webpack'
  },
  webpack: {
    ...
    module: {
      rules: [
        // instrument only testing sources with Istanbul
        {
          test: /\.js$/,
          use: { loader: 'istanbul-instrumenter-loader' },
          include: path.resolve('src/components/')
        }
      ]
    }
    ...
  },
  reporters: [ 'progress', 'coverage-istanbul' ],
  coverageIstanbulReporter: {
    reports: [ 'text-summary' ],
    fixWebpackSourcePaths: true
  }
  ...
});

with `Babel`

You must run the instrumentation as a post step

webpack.config.js

{
  test: /\.js$|\.jsx$/,
  use: {
    loader: 'istanbul-instrumenter-loader',
    options: { esModules: true }
  },
  enforce: 'post',
  exclude: /node_modules|\.spec\.js$/,
}

Options

The loader supports all options supported by istanbul-lib-instrument

Name	Type	Default	Description
Name Type Default Description `debug` `{Boolean}`	`{Boolean}`	`false`	Turn on debugging mode
Name Type Default Description `compact` `{Boolean}`	`{Boolean}`	`true`	Generate compact code
Name Type Default Description `autoWrap` `{Boolean}`	`{Boolean}`	`false`	Set to `true` to allow return statements outside of functions
Name Type Default Description `esModules` `{Boolean}`	`{Boolean}`	`false`	Set to `true` to instrument ES2015 Modules
Name Type Default Description `coverageVariable` `{String}`	`{String}`	`__coverage__`	Name of global coverage variable
Name Type Default Description `preserveComments` `{Boolean}`	`{Boolean}`	`false`	Preserve comments in `output`
Name Type Default Description `produceSourceMap` `{Boolean}`	`{Boolean}`	`false`	Set to `true` to produce a source map for the instrumented code
Name Type Default Description `sourceMapUrlCallback` `{Function}`	`{Function}`	`null`	A callback function that is called when a source map URL is found in the original code. This function is called with the source filename and the source map URL

webpack.config.js

{
  test: /\.js$/,
  use: {
    loader: 'istanbul-instrumenter-loader',
    options: {...options}
  }
}

Maintainers

Kir Belevich

jshint-loader

A JSHint loader module for webpack. Runs JSHint on JavaScript files in a bundle at build-time.

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install jshint-loader --save-dev

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

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /.js/,
        enforce: 'pre',
        exclude: /node_modules/,
        use: [
          {
            loader: `jshint-loader`,
            options: {...options}
          }
        ]
      }
    ]
  }
}

And run webpack via your preferred method.

Options

All valid JSHint options are valid on this object, in addition to the custom loader options listed below:

delete options.; delete options.; delete options.;

`emitErrors`

Type: Boolean Default: undefined

Instructs the loader to emit all JSHint warnings and errors as webpack errors.

`failOnHint`

Type: Boolean Default: undefined

Instructs the loader to cause the webpack build to fail on all JSHint warnings and errors.

`reporter`

Type: Function Default: undefined

A function used to format and emit JSHint warnings and errors.

Custom Reporter

By default, jshint-loader will provide a default reporter.

However, if you prefer a custom reporter, pass a function under the reporter property in jshint options. (see usage above)

The reporter function will be passed an array of errors/warnings produced by JSHint with the following structure:

[
{
    id:        [string, usually '(error)'],
    code:      [string, error/warning code],
    reason:    [string, error/warning message],
    evidence:  [string, a piece of code that generated this error]
    line:      [number]
    character: [number]
    scope:     [string, message scope;
                usually '(main)' unless the code was eval'ed]

    [+ a few other legacy fields that you don't need to worry about.]
},
// ...
// more errors/warnings
]

The reporter function will be excuted with the loader context as this. You may emit messages using this.emitWarning(...) or this.emitError(...). See webpack docs on loader context.

Note: JSHint reporters are not compatible with JSHint-loader! This is due to the fact that reporter input is only processed from one file; not multiple files. Error reporting in this manner differs from traditional reporters for JSHint since the loader plugin (i.e. JSHint-loader) is executed for each source file; and thus the reporter is executed for each file.

The output in webpack CLI will usually be:

...
WARNING in ./path/to/file.js
<reporter output>
...

Contributing

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

CONTRIBUTING

License

MIT

json-loader

Install

npm install --save-dev json-loader

⚠️ Since webpack >= v2.0.0, importing of JSON files will work by default. You might still want to use this if you use a custom file extension. See the v1.0.0 -> v2.0.0 Migration Guide for more information

Usage

`Inline`

const json = require('json-loader!./file.json');

`Configuration` (recommended)

const json = require('./file.json');

webpack.config.js

module.exports = {
  module: {
    loaders: [
      {
        test: /\.json$/,
        loader: 'json-loader'
      }
    ]
  }
}

Maintainer

Tobias Koppers

json5-loader

A webpack loader for parsing json5 files into JavaScript objects.

Getting Started

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

$ npm install json5-loader --save-dev

You can use the loader either:

by configuring the json5-loader in the module.rules object of the webpack configuration, or
by directly using the json5-loader! prefix to the require statement.

Suppose we have the following json5 file:

file.json5

{
  env: 'production',
  passwordStrength: 'strong',
}

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.json5$/i,
        loader: 'json5-loader',
        type: 'javascript/auto',
      },
    ],
  },
};

Options

Name	Type	Default	Description
Name Type Default Description `esModule` `{Boolean}`	`{Boolean}`	`true`	Uses ES modules syntax

`esModule`

Type: Boolean Default: true

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 ES module syntax using:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.json5$/i,
        loader: 'json5-loader',
        options: {
          esModule: false,
        },
        type: 'javascript/auto',
      },
    ],
  },
};

Examples

Usage with require statement loader prefix

file.json5

{
  env: 'production',
  passwordStrength: 'strong',
}

index.js

import appConfig from 'json5-loader!./file.json5';

console.log(appConfig.env); // 'production'

Don't forget to polyfill require if you want to use it in Node.js. See the webpack documentation.

Contributing

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

CONTRIBUTING

License

MIT

less-loader

A Less loader for webpack. Compiles Less to CSS.

Getting Started

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

$ npm install less-loader --save-dev

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

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        loader: 'less-loader', // compiles Less to CSS
      },
    ],
  },
};

And run webpack via your preferred method.

Options

`lessOptions`

Type: Object|Function

You can pass any Less specific options to the less-loader through the lessOptions property in the loader options. See the Less documentation for all available options in dash-case. Since we're passing these options to Less programmatically, you need to pass them in camelCase here:

`Object`

Use an object to pass options through to Less.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'style-loader',
          },
          {
            loader: 'css-loader',
          },
          {
            loader: 'less-loader',
            options: {
              lessOptions: {
                strictMath: true,
              },
            },
          },
        ],
      },
    ],
  },
};

`Function`

Allows setting the options passed through to Less based off of the loader context.

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'less-loader',
            options: {
              lessOptions: (loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === 'styles/foo.less') {
                  return {
                    paths: ['absolute/path/c', 'absolute/path/d'],
                  };
                }

                return {
                  paths: ['absolute/path/a', 'absolute/path/b'],
                };
              },
            },
          },
        ],
      },
    ],
  },
};

`prependData`

Type: String|Function Default: undefined

Prepends Less code before the actual entry file.

This is especially useful when some of your Less variables depend on the environment:

ℹ Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Less entry files.

`String`

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'less-loader',
            options: {
              prependData: `@env: ${process.env.NODE_ENV};`,
            },
          },
        ],
      },
    ],
  },
};

`Function`

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'less-loader',
            options: {
              prependData: (loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === 'styles/foo.less') {
                  return '@value: 100px;';
                }

                return '@value: 200px;';
              },
            },
          },
        ],
      },
    ],
  },
};

`appendData`

Type: String|Function Default: undefined

AppendData Less code after the actual entry file.

This can be useful when you need to rewrite some of your Less variables.:

ℹ Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Less entry files.

`String`

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'less-loader',
            options: {
              appendData: `@env: ${process.env.NODE_ENV};`,
            },
          },
        ],
      },
    ],
  },
};

`Function`

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'less-loader',
            options: {
              appendData: (loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === 'styles/foo.less') {
                  return '@value: 100px;';
                }

                return '@value: 200px;';
              },
            },
          },
        ],
      },
    ],
  },
};

`sourceMap`

Type: Boolean Default: depends on the compiler.devtool value

By default generation of source maps depends on the devtool option. All values enable source map generation except eval and false value.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/i,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              sourceMap: true,
            },
          },
          {
            loader: 'less-loader',
            options: {
              sourceMap: true,
            },
          },
        ],
      },
    ],
  },
};

Examples

Normal usage

Chain the less-loader with the css-loader and the style-loader to immediately apply all styles to the DOM.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'style-loader', // creates style nodes from JS strings
          },
          {
            loader: 'css-loader', // translates CSS into CommonJS
          },
          {
            loader: 'less-loader', // compiles Less to CSS
          },
        ],
      },
    ],
  },
};

Unfortunately, Less doesn't map all options 1-by-1 to camelCase. When in doubt, check their executable and search for the dash-case option.

Source maps

To enable sourcemaps for CSS, you'll need to pass the sourceMap property in the loader's options. If this is not passed, the loader will respect the setting for webpack source maps, set in devtool.

webpack.config.js

module.exports = {
  devtool: 'source-map', // any "source-map"-like devtool is possible
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              sourceMap: true,
            },
          },
          {
            loader: 'less-loader',
            options: {
              sourceMap: true,
            },
          },
        ],
      },
    ],
  },
};

If you want to edit the original Less files inside Chrome, there's a good blog post. The blog post is about Sass but it also works for Less.

In production

Usually, it's recommended to extract the style sheets into a dedicated file in production using the MiniCssExtractPlugin. This way your styles are not dependent on JavaScript.

Imports

Starting with less-loader 4, you can now choose between Less' builtin resolver and webpack's resolver. By default, webpack's resolver is used.

webpack resolver

webpack provides an advanced mechanism to resolve files. The less-loader applies a Less plugin that passes all queries to the webpack resolver. Thus you can import your Less modules from node_modules. Just prepend them with a ~ which tells webpack to look up the modules.

@import '~bootstrap/less/bootstrap';

It's important to only prepend it with ~, because ~/ resolves to the home-directory. webpack needs to distinguish between bootstrap and ~bootstrap, because CSS and Less files have no special syntax for importing relative files. Writing @import "file" is the same as @import "./file";

Non-Less imports

Using webpack's resolver, you can import any file type. You just need a loader that exports valid Less code. Often, you will also want to set the issuer condition to ensure that this rule is only applied on imports originating from Less files:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        issuer: /\.less$/,
        use: [
          {
            loader: 'js-to-less-loader',
          },
        ],
      },
    ],
  },
};

Less resolver

If you specify the paths option, modules will be searched in the given paths. This is Less' default behavior. paths should be an array with absolute paths:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'style-loader',
          },
          {
            loader: 'css-loader',
          },
          {
            loader: 'less-loader',
            options: {
              lessOptions: {
                paths: [path.resolve(__dirname, 'node_modules')],
              },
            },
          },
        ],
      },
    ],
  },
};

Plugins

In order to use plugins, simply set the plugins option like this:

// webpack.config.js
const CleanCSSPlugin = require('less-plugin-clean-css');

module.exports = {
  ...
    {
      loader: 'less-loader',
      options: {
        lessOptions: {
          plugins: [
            new CleanCSSPlugin({ advanced: true }),
          ],
        },
      },
    },
  ...
};

Extracting style sheets

Bundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or hot module replacement in development. In production, on the other hand, it's not a good idea to apply your style sheets depending on JS execution. Rendering may be delayed or even a FOUC might be visible. Thus it's often still better to have them as separate files in your final production build.

There are two possibilities to extract a style sheet from the bundle:

extract-loader (simpler, but specialized on the css-loader's output)
MiniCssExtractPlugin (more complex, but works in all use-cases)

CSS modules gotcha

There is a known problem with Less and CSS modules regarding relative file paths in url(...) statements. See this issue for an explanation.

Contributing

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

CONTRIBUTING

License

MIT

mocha-loader

Allows Mocha tests to be loaded and run via webpack

Install

npm i -D mocha-loader

Usage

CLI

webpack --module-bind 'mocha-loader!./test'

Require

import test from 'mocha-loader!./test';

Config (recommended)

import test from './test';

webpack.config.js

module.exports = {
  entry: './entry.js',
  output: {
    path: __dirname,
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /test\.js$/,
        use: 'mocha-loader',
        exclude: /node_modules/,
      },
    ],
  },
};

Options

None

Examples

Basic

module.js

module.exports = true;

test.js

describe('Test', () => {
  it('should succeed', (done) => {
    setTimeout(done, 1000);
  });

  it('should fail', () => {
    setTimeout(() => {
      throw new Error('Failed');
    }, 1000);
  });

  it('should randomly fail', () => {
    if (require('./module')) {
      throw new Error('Randomly failed');
    }
  });
});

multi-loader

A webpack loader for splitting modules and using multiple loaders. This loader requires a module multiple times, each time loaded with different loaders, as defined in your config.

Note: In a multi-entry, the exports of the last item are exported.

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install multi-loader --save-dev

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

// webpack.config.js
const multi = require('multi-loader');
{
	module: {
		loaders: [
			{
				test: /\.css$/,
				// Add CSS to the DOM and return the raw content
				loader: multi(
					'style-loader!css-loader!autoprefixer-loader',
					'raw-loader'
				)
			}
		]
	}
}

And run webpack via your preferred method.

License

MIT

node-loader

A Node.js add-ons loader module for enhanced-require. Executes add-ons in enhanced-require.

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install node-loader --save-dev

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

import node from 'file.node';

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.node$/,
        use: 'node-loader'
      }
    ]
  }
}

Or on the command-line:

$ webpack --module-bind 'node=node-loader'

Inline

In your application

import node from 'node-loader!./file.node';

And run webpack via your preferred method.

License

MIT

null-loader

A webpack loader that returns an empty module.

One use for this loader is to silence modules imported by a dependency. Say, for example, your project relies on an ES6 library that imports a polyfill you don't need, so removing it will cause no loss in functionality.

Getting Started

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

$ npm install null-loader --save-dev

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

// webpack.config.js
const path = require('path');

module.exports = {
  module: {
    rules: [
      {
        // Test for a polyfill (or any file) and it won't be included in your
        // bundle
        test: path.resolve(__dirname, 'node_modules/library/polyfill.js'),
        use: 'null-loader',
      },
    ],
  },
};

And run webpack via your preferred method.

Contributing

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

CONTRIBUTING

License

MIT

polymer-webpack-loader

Polymer component loader for webpack.

The loader processes Polymer 3 template elements to minify the html and add images, fonts and imported stylesheets to the webpack dependency graph.

Looking for the Polymer 2 version? See the Polymer 2 branch

Configuring the Loader

{
  test: /\.js$/,
  options: {
    htmlLoader: Object (optional)
  },
  loader: 'polymer-webpack-loader'
},

Options

htmlLoader: Object

Options to pass to the html-loader. See html-loader.

Use with Babel (or other JS transpilers)

If you'd like to transpile the contents of your element you can chain an additional loader.

module: {
  loaders: [
    {
      test: /\.html$/,
      use: [
        // Chained loaders are applied last to first
        { loader: 'babel-loader' },
        { loader: 'polymer-webpack-loader' }
      ]
    }
  ]
}

// alternative syntax

module: {
  loaders: [
    {
      test: /\.html$/,
      // Chained loaders are applied right to left
      loader: 'babel-loader!polymer-webpack-loader'
    }
  ]
}

Boostrapping Your Application

The webcomponent polyfills must be added in a specific order. If you do not delay loading the main bundle with your components, you will see the following exceptions in the browser console:

Uncaught TypeError: Failed to construct 'HTMLElement': Please use the 'new' operator, this DOM object constructor cannot be called as a function.

Reference the demo html file for the proper loading sequence.

Maintainers

Bryan Coulter

Chad Killingsworth

Rob Dodson

postcss-loader

Loader for webpack to process CSS with PostCSS

Install

npm i -D postcss-loader

Usage

`Configuration`

postcss.config.js

module.exports = {
  parser: 'sugarss',
  plugins: {
    'postcss-import': {},
    'postcss-preset-env': {},
    'cssnano': {}
  }
}

You can read more about common PostCSS Config here.

`Config Cascade`

You can use different postcss.config.js files in different directories. Config lookup starts from path.dirname(file) and walks the file tree upwards until a config file is found.

|– components
| |– component
| | |– index.js
| | |– index.png
| | |– style.css (1)
| | |– postcss.config.js (1)
| |– component
| | |– index.js
| | |– image.png
| | |– style.css (2)
|
|– postcss.config.js (1 && 2 (recommended))
|– webpack.config.js
|
|– package.json

After setting up your postcss.config.js, add postcss-loader to your webpack.config.js. You can use it standalone or in conjunction with css-loader (recommended). Use it after css-loader and style-loader, but before other preprocessor loaders like e.g sass|less|stylus-loader, if you use any.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [ 'style-loader', 'postcss-loader' ]
      }
    ]
  }
}

⚠️ When postcss-loader is used standalone (without css-loader) don't use @import in your CSS, since this can lead to quite bloated bundles

webpack.config.js (recommended)

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          { loader: 'css-loader', options: { importLoaders: 1 } },
          'postcss-loader'
        ]
      }
    ]
  }
}

Options

Name	Type	Default	Description
Name Type Default Description `exec` `{Boolean}`	`{Boolean}`	`undefined`	Enable PostCSS Parser support in `CSS-in-JS`
Name Type Default Description `parser` `{String\\|Object}`	`{String\\|Object}`	`undefined`	Set PostCSS Parser
Name Type Default Description `syntax` `{String\\|Object}`	`{String\\|Object}`	`undefined`	Set PostCSS Syntax
Name Type Default Description `stringifier` `{String\\|Object}`	`{String\\|Object}`	`undefined`	Set PostCSS Stringifier
Name Type Default Description `config` `{Object}`	`{Object}`	`undefined`	Set `postcss.config.js` config path && `ctx`
Name Type Default Description `plugins` `{Array\\|Function}`	`{Array\\|Function}`	`[]`	Set PostCSS Plugins
Name Type Default Description `sourceMap` `{String\\|Boolean}`	`{String\\|Boolean}`	`false`	Enable Source Maps

`Exec`

If you use JS styles without the postcss-js parser, add the exec option.

webpack.config.js

{
  test: /\.style.js$/,
  use: [
    'style-loader',
    { loader: 'css-loader', options: { importLoaders: 1 } },
    { loader: 'postcss-loader', options: { parser: 'sugarss', exec: true } }
  ]
}

`Config`

Name	Type	Default	Description
Name Type Default Description `path` `{String}`	`{String}`	`undefined`	PostCSS Config Directory
Name Type Default Description `context` `{Object}`	`{Object}`	`undefined`	PostCSS Config Context

`Path`

You can manually specify the path to search for your config (postcss.config.js) with the config.path option. This is needed if you store your config in a separate e.g ./config || ./.config folder.

⚠️ Otherwise it is unnecessary to set this option and is not recommended

⚠️ Note that you can't use a filename other than the supported config formats (e.g .postcssrc.js, postcss.config.js), this option only allows you to manually specify the directory where config lookup should start from

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    config: {
      path: 'path/to/.config/' ✅
      path: 'path/to/.config/css.config.js' ❌
    }
  }
}

`Context (ctx)`

Name	Type	Default	Description
Name Type Default Description `env` `{String}`	`{String}`	`'development'`	`process.env.NODE_ENV`
Name Type Default Description `file` `{Object}`	`{Object}`	`loader.resourcePath`	`extname` , `dirname` , `basename`
Name Type Default Description `options` `{Object}`	`{Object}`	`{}`	Options

postcss-loader exposes context ctx to the config file, making your postcss.config.js dynamic, so can use it to do some real magic ✨

postcss.config.js

module.exports = ({ file, options, env }) => ({
  parser: file.extname === '.sss' ? 'sugarss' : false,
  plugins: {
    'postcss-import': { root: file.dirname },
    'postcss-preset-env': options['postcss-preset-env'] ? options['postcss-preset-env'] : false,
    'cssnano': env === 'production' ? options.cssnano : false
  }
})

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    config: {
      ctx: {
        'postcss-preset-env': {...options},
        cssnano: {...options},
      }
    }
  }
}

`Plugins`

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    ident: 'postcss',
    plugins: (loader) => [
      require('postcss-import')({ root: loader.resourcePath }),
      require('postcss-preset-env')(),
      require('cssnano')()
    ]
  }
}

⚠️ webpack requires an identifier (ident) in options when {Function}/require is used (Complex Options). The ident can be freely named as long as it is unique. It's recommended to name it (ident: 'postcss')

`Syntaxes`

Name	Type	Default	Description
Name Type Default Description `parser` `{String\\|Function}`	`{String\\|Function}`	`undefined`	Custom PostCSS Parser
Name Type Default Description `syntax` `{String\\|Function}`	`{String\\|Function}`	`undefined`	Custom PostCSS Syntax
Name Type Default Description `stringifier` `{String\\|Function}`	`{String\\|Function}`	`undefined`	Custom PostCSS Stringifier

`Parser`

webpack.config.js

{
  test: /\.sss$/,
  use: [
    ...,
    { loader: 'postcss-loader', options: { parser: 'sugarss' } }
  ]
}

`Syntax`

webpack.config.js

{
  test: /\.css$/,
  use: [
    ...,
    { loader: 'postcss-loader', options: { syntax: 'sugarss' } }
  ]
}

`Stringifier`

webpack.config.js

{
  test: /\.css$/,
  use: [
    ...,
    { loader: 'postcss-loader', options: { stringifier: 'midas' } }
  ]
}

`SourceMap`

Enables source map support, postcss-loader will use the previous source map given by other loaders and update it accordingly, if no previous loader is applied before postcss-loader, the loader will generate a source map for you.

webpack.config.js

{
  test: /\.css/,
  use: [
    { loader: 'style-loader', options: { sourceMap: true } },
    { loader: 'css-loader', options: { sourceMap: true } },
    { loader: 'postcss-loader', options: { sourceMap: true } },
    { loader: 'sass-loader', options: { sourceMap: true } }
  ]
}

`'inline'`

You can set the sourceMap: 'inline' option to inline the source map within the CSS directly as an annotation comment.

webpack.config.js

{
  loader: 'postcss-loader',
  options: {
    sourceMap: 'inline'
  }
}

.class { color: red; }

/*# sourceMappingURL=data:application/json;base64, ... */

Examples

`Stylelint`

webpack.config.js

{
  test: /\.css$/,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'postcss-loader',
      options: {
        ident: 'postcss',
        plugins: [
          require('postcss-import')(),
          require('stylelint')(),
          ...,
        ]
      }
    }
  ]
}

`Autoprefixing`

webpack.config.js

{
  test: /\.css$/,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'postcss-loader',
      options: {
        ident: 'postcss',
        plugins: [
          require('autoprefixer')({...options}),
          ...,
        ]
      }
    }
  ]
}

:warning: postcss-preset-env includes autoprefixer, so adding it separately is not necessary if you already use the preset.

`CSS Modules`

This loader cannot be used with CSS Modules out of the box due to the way css-loader processes file imports. To make them work properly, either add the css-loader’s importLoaders option.

webpack.config.js

{
  test: /\.css$/,
  use: [
    'style-loader',
    { loader: 'css-loader', options: { modules: true, importLoaders: 1 } },
    'postcss-loader'
  ]
}

or use postcss-modules instead of css-loader.

`CSS-in-JS`

If you want to process styles written in JavaScript, use the postcss-js parser.

webpack.config.js

{
  test: /\.style.js$/,
  use: [
    'style-loader',
    { loader: 'css-loader', options: { importLoaders: 2 } },
    { loader: 'postcss-loader', options: { parser: 'postcss-js' } },
    'babel-loader'
  ]
}

As result you will be able to write styles in the following way

import colors from './styles/colors'

export default {
    '.menu': {
      color: colors.main,
      height: 25,
      '&_link': {
      color: 'white'
    }
  }
}

:warning: If you are using Babel you need to do the following in order for the setup to work

Add babel-plugin-add-module-exports to your configuration

You need to have only one default export per style module

Extract CSS

webpack.config.js

const devMode = process.env.NODE_ENV !== 'production'

const MiniCssExtractPlugin = require('mini-css-extract-plugin')

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          devMode ? 'style-loader' : MiniCssExtractPlugin.loader,
          'css-loader',
          'postcss-loader'
        ]
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: devMode ? '[name].css' : '[name].[hash].css'
    })
  ]
}

Maintainers

Michael Ciniawsky

Alexander Krasnoyarov

raw-loader

A loader for webpack that allows importing files as a String.

Getting Started

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

$ npm install raw-loader --save-dev

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

file.js

import txt from './file.txt';

webpack.config.js

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.txt$/i,
        use: 'raw-loader',
      },
    ],
  },
};

And run webpack via your preferred method.

Options

Name	Type	Default	Description
Name Type Default Description `esModule` `{Boolean}`	`{Boolean}`	`true`	Uses ES modules syntax

`esModule`

Type: Boolean Default: true

By default, raw-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: /\.txt$/i,
        use: [
          {
            loader: 'raw-loader',
            options: {
              esModule: false,
            },
          },
        ],
      },
    ],
  },
};

Examples

Inline

import txt from 'raw-loader!./file.txt';

Beware, if you already define loader(s) for extension(s) in webpack.config.js you should use:

import css from '!!raw-loader!./file.txt'; // Adding `!!` to a request will disable all loaders specified in the configuration

Contributing

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

CONTRIBUTING

License

MIT

react-proxy-loader

Wraps a react component in a proxy component to enable Code Splitting, which loads a react component and its dependencies on demand.

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install react-proxy-loader --save-dev

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

// returns the proxied component, loaded on demand
// webpack creates an additional chunk for this component and its dependencies
const Component = require('react-proxy-loader!./Component');

// returns a mixin for the proxied component
// This allows you to setup rendering for the loading state for the proxy
const ComponentProxyMixin = require('react-proxy-loader!./Component').Mixin;

const ComponentProxy = React.createClass({
	mixins: [ComponentProxyMixin],
	renderUnavailable: function() {
		return <p>Loading...</p>;
	}
});

Or specify the proxied components in your configuration:

// webpack.config.js
module.exports = {
	module: {
		loaders: [
			/* ... */
			{
				test: [
					/component\.jsx$/, // select component by RegExp
					/\.async\.jsx$/, // select component by extension
					"/abs/path/to/component.jsx" // absolute path to component
				],
				loader: "react-proxy-loader"
			}
		]
	}
};

Or provide a chunk name within a name query parameter:

var Component = require("react-proxy-loader?name=chunkName!./Component");

And run webpack via your preferred method.

License

MIT

restyle-loader

Updates style <link> href value with a hash to trigger a style reload

Loader new home: restyle-loader

Install

npm install --save-dev restyle-loader

Usage

Documentation: Using loaders

Examples

webpack.config.js

{
  test: /\.css?$/,
  use: [
    {
      loader: "restyle-loader"
    },
    {
      loader: "file-loader",
      options: {
        name: "[name].css?[hash:8]"
      }
    }
  ]
}

Hash is required to enable HMR

bundle.js

require("./index.css");

// Bundle code here...

index.html

<head>
  <link rel="stylesheet" type="text/css" href="css/index.css">
</head>

after the loader runs it becomes

<head>
  <link rel="stylesheet" type="text/css" href="css/index.css?531fdfd0">
</head>

Maintainers

Daniel Verejan

sass-loader

Loads a Sass/SCSS file and compiles it to CSS.

Getting Started

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

npm install sass-loader sass webpack --save-dev

sass-loader requires you to install either Dart Sass on your own (more documentation can be found below) or Node Sass. This allows you to control the versions of all your dependencies, and to choose which Sass implementation to use.

Chain the sass-loader with the css-loader and the style-loader to immediately apply all styles to the DOM or the mini-css-extract-plugin to extract it into a separate file.

Then add the loader to your Webpack configuration. For example:

app.js

import './style.scss';

style.scss

$body-color: red;

body {
  color: $body-color;
}

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          // Creates `style` nodes from JS strings
          'style-loader',
          // Translates CSS into CommonJS
          'css-loader',
          // Compiles Sass to CSS
          'sass-loader',
        ],
      },
    ],
  },
};

Finally run webpack via your preferred method.

Resolving `import` at-rules

Webpack provides an advanced mechanism to resolve files.

The sass-loader uses Sass's custom importer feature to pass all queries to the Webpack resolving engine. Thus you can import your Sass modules from node_modules. Just prepend them with a ~ to tell Webpack that this is not a relative import:

@import '~bootstrap';

It's important to only prepend it with ~, because ~/ resolves to the home directory. Webpack needs to distinguish between bootstrap and ~bootstrap because CSS and Sass files have no special syntax for importing relative files. Writing @import "style.scss" is the same as @import "./style.scss";

Problems with `url(...)`

Since Sass implementations don't provide url rewriting, all linked assets must be relative to the output.

If you pass the generated CSS on to the css-loader, all urls must be relative to the entry-file (e.g. main.scss).
If you're just generating CSS without passing it to the css-loader, it must be relative to your web root.

You will be disrupted by this first issue. It is natural to expect relative references to be resolved against the .sass/.scss file in which they are specified (like in regular .css files).

Thankfully there are a two solutions to this problem:

Add the missing url rewriting using the resolve-url-loader. Place it before sass-loader in the loader chain.
Library authors usually provide a variable to modify the asset path. bootstrap-sass for example has an $icon-font-path.

Options

Name	Type	Default	Description
Name Type Default Description `implementation` `{Object}`	`{Object}`	`sass`	Setup Sass implementation to use.
Name Type Default Description `sassOptions` `{Object\\|Function}`	`{Object\\|Function}`	defaults values for Sass implementation	Options for Sass.
Name Type Default Description `sourceMap` `{Boolean}`	`{Boolean}`	`compiler.devtool`	Enables/Disables generation of source maps.
Name Type Default Description `prependData` `{String\\|Function}`	`{String\\|Function}`	`undefined`	Prepends `Sass` / `SCSS` code before the actual entry file.
Name Type Default Description `webpackImporter` `{Boolean}`	`{Boolean}`	`true`	Enables/Disables the default Webpack importer.

`implementation`

Type: Object Default: sass

The special implementation option determines which implementation of Sass to use.

By default the loader resolve the implementation based on your dependencies. Just add required implementation to package.json (sass or node-sass package) and install dependencies.

Example where the sass-loader loader uses the sass (dart-sass) implementation:

package.json

{
  "devDependencies": {
    "sass-loader": "^7.2.0",
    "sass": "^1.22.10"
  }
}

Example where the sass-loader loader uses the node-sass implementation:

package.json

{
  "devDependencies": {
    "sass-loader": "^7.2.0",
    "node-sass": "^4.0.0"
  }
}

Beware the situation when node-sass and sass were installed! By default the sass-loader prefers sass. In order to avoid this situation you can use the implementation option.

The implementation options either accepts sass (Dart Sass) or node-sass as a module.

For example, to use Dart Sass, you'd pass:

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              // Prefer `dart-sass`
              implementation: require('sass'),
            },
          },
        ],
      },
    ],
  },
};

Note that when using sass (Dart Sass), synchronous compilation is twice as fast as asynchronous compilation by default, due to the overhead of asynchronous callbacks. To avoid this overhead, you can use the fibers package to call asynchronous importers from the synchronous code path.

We automatically inject the fibers package (setup sassOptions.fiber) if is possible (i.e. you need install the fibers package).

package.json

{
  "devDependencies": {
    "sass-loader": "^7.2.0",
    "sass": "^1.22.10",
    "fibers": "^4.0.1"
  }
}

You can disable automatically injecting the fibers package by passing a false value for the sassOptions.fiber option.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              implementation: require('sass'),
              sassOptions: {
                fiber: false,
              },
            },
          },
        ],
      },
    ],
  },
};

You can also pass the fiber value using this code:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              implementation: require('sass'),
              sassOptions: {
                fiber: require('fibers'),
              },
            },
          },
        ],
      },
    ],
  },
};

`sassOptions`

Type: Object|Function Default: defaults values for Sass implementation

Options for Dart Sass or Node Sass implementation.

ℹ️ The indentedSyntax option has true value for the sass extension.

ℹ️ Options such as data and file are unavailable and will be ignored.

ℹ We recommend not to set the outFile, sourceMapContents, sourceMapEmbed, sourceMapRoot options because sass-loader automatically sets these options when the sourceMap option is true.

There is a slight difference between the sass (dart-sass) and node-sass options.

Please consult documentation before using them:

Dart Sass documentation for all available sass options.
Node Sass documentation for all available node-sass options.

`Object`

Use and object for the Sass implementation setup.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              sassOptions: {
                indentWidth: 4,
                includePaths: ['absolute/path/a', 'absolute/path/b'],
              },
            },
          },
        ],
      },
    ],
  },
};

`Function`

Allows to setup the Sass implementation by setting different options based on the loader context.

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              sassOptions: (loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === 'styles/foo.scss') {
                  return {
                    includePaths: ['absolute/path/c', 'absolute/path/d'],
                  };
                }

                return {
                  includePaths: ['absolute/path/a', 'absolute/path/b'],
                };
              },
            },
          },
        ],
      },
    ],
  },
};

`sourceMap`

Type: Boolean Default: depends on the compiler.devtool value

Enables/Disables generation of source maps.

By default generation of source maps depends on the devtool option. All values enable source map generation except eval and false value.

ℹ If a true the sourceMap, sourceMapRoot, sourceMapEmbed, sourceMapContents and omitSourceMapUrl from sassOptions will be ignored.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              sourceMap: true,
            },
          },
          {
            loader: 'sass-loader',
            options: {
              sourceMap: true,
            },
          },
        ],
      },
    ],
  },
};

ℹ In some rare cases node-sass can output invalid source maps (it is a node-sass bug). In order to avoid this, you can try to update node-sass to latest version or you can try to set within sassOptions the outputStyle option to compressed.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              sourceMap: true,
              sassOptions: {
                outputStyle: 'compressed',
              },
            },
          },
        ],
      },
    ],
  },
};

`prependData`

Type: String|Function Default: undefined

Prepends Sass/SCSS code before the actual entry file. In this case, the sass-loader will not override the data option but just append the entry's content.

This is especially useful when some of your Sass variables depend on the environment:

ℹ Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Sass entry files.

`String`

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              prependData: '$env: ' + process.env.NODE_ENV + ';',
            },
          },
        ],
      },
    ],
  },
};

`Function`

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              prependData: (loaderContext) => {
                // More information about available properties https://webpack.js.org/api/loaders/
                const { resourcePath, rootContext } = loaderContext;
                const relativePath = path.relative(rootContext, resourcePath);

                if (relativePath === 'styles/foo.scss') {
                  return '$value: 100px;';
                }

                return '$value: 200px;';
              },
            },
          },
        ],
      },
    ],
  },
};

`webpackImporter`

Type: Boolean Default: true

Enables/Disables the default Webpack importer.

This can improve performance in some cases. Use it with caution because aliases and @import at-rules starting with ~ will not work. You can pass own importer to solve this (see importer docs).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              webpackImporter: false,
            },
          },
        ],
      },
    ],
  },
};

Examples

Extracts CSS into separate files

For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.

There are two possibilities to extract a style sheet from the bundle:

mini-css-extract-plugin (use this, when using webpack 4 configuration. Works in all use-cases)
extract-loader (simpler, but specialized on the css-loader's output)

webpack.config.js

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          // fallback to style-loader in development
          process.env.NODE_ENV !== 'production'
            ? 'style-loader'
            : MiniCssExtractPlugin.loader,
          'css-loader',
          'sass-loader',
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: '[name].css',
      chunkFilename: '[id].css',
    }),
  ],
};

Source maps

Enables/Disables generation of source maps.

To enable CSS source maps, you'll need to pass the sourceMap option to the sass-loader and the css-loader.

webpack.config.js

module.exports = {
  devtool: 'source-map', // any "source-map"-like devtool is possible
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              sourceMap: true,
            },
          },
          {
            loader: 'sass-loader',
            options: {
              sourceMap: true,
            },
          },
        ],
      },
    ],
  },
};

If you want to edit the original Sass files inside Chrome, there's a good blog post. Checkout test/sourceMap for a running example.

Contributing

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

CONTRIBUTING

License

MIT

script-loader

Install

npm install --save-dev script-loader

Usage

Executes JS script once in global context.

:warning: Doesn't work in NodeJS

Config (recommended)

import './script.exec.js';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.exec\.js$/,
        use: [ 'script-loader' ]
      }
    ]
  }
}

Inline

import 'script-loader!./script.js';

Options

Name	Type	Default	Description
Name Type Default Description `sourceMap` `{Boolean}`	`{Boolean}`	`false`	Enable/Disable Sourcemaps
Name Type Default Description `useStrict` `{Boolean}`	`{Boolean}`	`true`	Enable/Disable useStrict

`sourceMap`

Type: Boolean Default: false

To include source maps set the sourceMap option.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.script\.js$/,
        use: [
          {
            loader: 'script-loader',
            options: {
              sourceMap: true,
            },
          },
        ]
      }
    ]
  }
}

`useStrict`

Type: Boolean Default: true

To disable use strict set the useStrict option to false.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.script\.js$/,
        use: [
          {
            loader: 'script-loader',
            options: {
              useStrict: false,
            },
          },
        ]
      }
    ]
  }
}

Maintainers

Juho Vepsäläinen

Joshua Wiens

Kees Kluskens

Sean Larkin

source-map-loader

Extracts source maps from existing source files (from their sourceMappingURL).

Install

npm i -D source-map-loader

Usage

Documentation: Using loaders

Example webpack config

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: ["source-map-loader"],
        enforce: "pre"
      }
    ]
  }
};

source-map-loader extracts existing source maps from all JavaScript entries. This includes both inline source maps as well as those linked via URL. All source map data is passed to webpack for processing as per a chosen source map style specified by the devtool option in webpack.config.js.

This loader is especially useful when using 3rd-party libraries having their own source maps. If not extracted and processed into the source map of the webpack bundle, browsers may misinterpret source map data. source-map-loader allows webpack to maintain source map data continuity across libraries so ease of debugging is preserved.

source-map-loader will extract from any JavaScript file, including those in the node_modules directory. Be mindful in setting include and exclude rule conditions to maximize bundling performance.

Maintainers

Juho Vepsäläinen

Joshua Wiens

Kees Kluskens

Sean Larkin

style-loader

Inject CSS into the DOM.

Getting Started

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

npm install --save-dev style-loader

It's recommended to combine style-loader with the css-loader

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

style.css

body {
  background: green;
}

component.js

import './style.css';

webpack.config.js

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

Options

Name	Type	Default	Description
Name Type Default Description `injectType` `{String}`	`{String}`	`styleTag`	Allows to setup how styles will be injected into the DOM
Name Type Default Description `attributes` `{Object}`	`{Object}`	`{}`	Adds custom attributes to tag
Name Type Default Description `insert` `{String\\|Function}`	`{String\\|Function}`	`head`	Inserts tag at the given position into the DOM
Name Type Default Description `base` `{Number}`	`{Number}`	`true`	Sets module ID base (DLLPlugin)
Name Type Default Description `esModule` `{Boolean}`	`{Boolean}`	`false`	Use ES modules syntax

`injectType`

Type: String Default: styleTag

Allows to setup how styles will be injected into the DOM.

Possible values:

styleTag
singletonStyleTag
lazyStyleTag
lazySingletonStyleTag
linkTag

`styleTag`

Automatically injects styles into the DOM using multiple <style></style>. It is default behaviour.

component.js

import './styles.css';

Example with Locals (CSS Modules):

component-with-css-modules.js

import styles from './styles.css';

const divElement = document.createElement('div');
divElement.className = styles['my-class'];

All locals (class names) stored in imported object.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          // The `injectType`  option can be avoided because it is default behaviour
          { loader: 'style-loader', options: { injectType: 'styleTag' } },
          'css-loader',
        ],
      },
    ],
  },
};

The loader inject styles like:

<style>
  .foo {
    color: red;
  }
</style>
<style>
  .bar {
    color: blue;
  }
</style>

`singletonStyleTag`

Automatically injects styles into the DOM using one <style></style>.

⚠ Source maps do not work.

component.js

import './styles.css';

component-with-css-modules.js

import styles from './styles.css';

const divElement = document.createElement('div');
divElement.className = styles['my-class'];

All locals (class names) stored in imported object.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'style-loader',
            options: { injectType: 'singletonStyleTag' },
          },
          'css-loader',
        ],
      },
    ],
  },
};

The loader inject styles like:

<style>
  .foo {
    color: red;
  }
  .bar {
    color: blue;
  }
</style>

`lazyStyleTag`

Injects styles into the DOM using multiple <style></style> on demand. We recommend following .lazy.css naming convention for lazy styles and the .css for basic style-loader usage (similar to other file types, i.e. .lazy.less and .less). When you lazyStyleTag value the style-loader injects the styles lazily making them useable on-demand via style.use() / style.unuse().

⚠️ Behavior is undefined when unuse is called more often than use. Don't do that.

component.js

import styles from './styles.lazy.css';

styles.use();
// For removing styles you can use
// styles.unuse();

component-with-css-modules.js

import styles from './styles.lazy.css';

styles.use();

const divElement = document.createElement('div');
divElement.className = styles.locals['my-class'];

All locals (class names) stored in locals property of imported object.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        exclude: /\.lazy\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
      {
        test: /\.lazy\.css$/i,
        use: [
          { loader: 'style-loader', options: { injectType: 'lazyStyleTag' } },
          'css-loader',
        ],
      },
    ],
  },
};

The loader inject styles like:

<style>
  .foo {
    color: red;
  }
</style>
<style>
  .bar {
    color: blue;
  }
</style>

`lazySingletonStyleTag`

Injects styles into the DOM using one <style></style> on demand. We recommend following .lazy.css naming convention for lazy styles and the .css for basic style-loader usage (similar to other file types, i.e. .lazy.less and .less). When you lazySingletonStyleTag value the style-loader injects the styles lazily making them useable on-demand via style.use() / style.unuse().

⚠️ Source maps do not work.

⚠️ Behavior is undefined when unuse is called more often than use. Don't do that.

component.js

import styles from './styles.css';

styles.use();
// For removing styles you can use
// styles.unuse();

component-with-css-modules.js

import styles from './styles.lazy.css';

styles.use();

const divElement = document.createElement('div');
divElement.className = styles.locals['my-class'];

All locals (class names) stored in locals property of imported object.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        exclude: /\.lazy\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
      {
        test: /\.lazy\.css$/i,
        use: [
          {
            loader: 'style-loader',
            options: { injectType: 'lazySingletonStyleTag' },
          },
          'css-loader',
        ],
      },
    ],
  },
};

The loader generate this:

<style>
  .foo {
    color: red;
  }
  .bar {
    color: blue;
  }
</style>

`linkTag`

Injects styles into the DOM using multiple <link rel="stylesheet" href="path/to/file.css"> .

ℹ️ The loader will dynamically insert the <link href="path/to/file.css" rel="stylesheet"> tag at runtime via JavaScript. You should use MiniCssExtractPlugin if you want to include a static <link href="path/to/file.css" rel="stylesheet">.

import './styles.css';
import './other-styles.css';

webpack.config.js

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

The loader generate this:

<link rel="stylesheet" href="path/to/style.css" />
<link rel="stylesheet" href="path/to/other-styles.css" />

`attributes`

Type: Object Default: {}

If defined, the style-loader will attach given attributes with their values on <style> / <link> element.

component.js

import style from './file.css';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: 'style-loader', options: { attributes: { id: 'id' } } },
          { loader: 'css-loader' },
        ],
      },
    ],
  },
};

<style id="id"></style>

`insert`

Type: String|Function Default: head

By default, the style-loader appends <style>/<link> elements to the end of the style target, which is the <head> tag of the page unless specified by insert. This will cause CSS created by the loader to take priority over CSS already present in the target. You can use other values if the standard behavior is not suitable for you, but we do not recommend doing this. If you target an iframe make sure you have sufficient access rights, the styles will be injected into the content document head.

`String`

Allows to setup custom query selector where styles inject into the DOM.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'style-loader',
            options: {
              insert: 'body',
            },
          },
          'css-loader',
        ],
      },
    ],
  },
};

A new <style>/<link> elements will be inserted into at bottom of body tag.

`Function`

Allows to override default behavior and insert styles at any position.

⚠ Do not forget that this code will be used in the browser and not all browsers support latest ECMA features like let, const, arrow function expression and etc, we recommend use only ECMA 5 features, but it is depends what browsers you want to support ⚠ Do not forget that some DOM methods may not be available in older browsers, we recommended use only DOM core level 2 properties, but it is depends what browsers you want to support

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'style-loader',
            options: {
              insert: function insertAtTop(element) {
                var parent = document.querySelector('head');
                // eslint-disable-next-line no-underscore-dangle
                var lastInsertedElement =
                  window._lastElementInsertedByStyleLoader;

                if (!lastInsertedElement) {
                  parent.insertBefore(element, parent.firstChild);
                } else if (lastInsertedElement.nextSibling) {
                  parent.insertBefore(element, lastInsertedElement.nextSibling);
                } else {
                  parent.appendChild(element);
                }

                // eslint-disable-next-line no-underscore-dangle
                window._lastElementInsertedByStyleLoader = element;
              },
            },
          },
          'css-loader',
        ],
      },
    ],
  },
};

Insert styles at top of head tag.

`base`

This setting is primarily used as a workaround for css clashes when using one or more DllPlugin's. base allows you to prevent either the app's css (or DllPlugin2's css) from overwriting DllPlugin1's css by specifying a css module id base which is greater than the range used by DllPlugin1 e.g.:

webpack.dll1.config.js

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

webpack.dll2.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: 'style-loader', options: { base: 1000 } },
          'css-loader',
        ],
      },
    ],
  },
};

webpack.app.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: 'style-loader', options: { base: 2000 } },
          'css-loader',
        ],
      },
    ],
  },
};

`esModule`

Type: Boolean Default: false

By default, style-loader generates JS modules that use the CommonJS 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 ES module syntax using:

webpack.config.js

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

Examples

Source maps

The loader automatically inject source maps when previous loader emit them. Therefore, to generate source maps, set the sourceMap option to true for the previous loader.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          'style-loader',
          { loader: 'css-loader', options: { sourceMap: true } },
        ],
      },
    ],
  },
};

Nonce

There are two ways to work with nonce:

using the attributes option
using the __webpack_nonce__ variable

⚠ the attributes option takes precedence over the __webpack_nonce__ variable

`attributes`

component.js

import './style.css';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'style-loader',
            options: {
              attributes: {
                nonce: '12345678',
              },
            },
          },
          'css-loader',
        ],
      },
    ],
  },
};

The loader generate:

<style nonce="12345678">
  .foo {
    color: red;
  }
</style>

`__webpack_nonce__`

create-nonce.js

__webpack_nonce__ = '12345678';

component.js

import './create-nonce.js';
import './style.css';

Alternative example for require:

component.js

__webpack_nonce__ = '12345678';

require('./style.css');

webpack.config.js

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

The loader generate:

<style nonce="12345678">
  .foo {
    color: red;
  }
</style>

Insert styles at top

Inserts styles at top of head tag.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'style-loader',
            options: {
              insert: function insertAtTop(element) {
                var parent = document.querySelector('head');
                var lastInsertedElement =
                  window._lastElementInsertedByStyleLoader;

                if (!lastInsertedElement) {
                  parent.insertBefore(element, parent.firstChild);
                } else if (lastInsertedElement.nextSibling) {
                  parent.insertBefore(element, lastInsertedElement.nextSibling);
                } else {
                  parent.appendChild(element);
                }

                window._lastElementInsertedByStyleLoader = element;
              },
            },
          },
          'css-loader',
        ],
      },
    ],
  },
};

Insert styles before target element

Inserts styles before #id element.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'style-loader',
            options: {
              insert: function insertBeforeAt(element) {
                const parent = document.querySelector('head');
                const target = document.querySelector('#id');

                const lastInsertedElement =
                  window._lastElementInsertedByStyleLoader;

                if (!lastInsertedElement) {
                  parent.insertBefore(element, target);
                } else if (lastInsertedElement.nextSibling) {
                  parent.insertBefore(element, lastInsertedElement.nextSibling);
                } else {
                  parent.appendChild(element);
                }

                window._lastElementInsertedByStyleLoader = element;
              },
            },
          },
          'css-loader',
        ],
      },
    ],
  },
};

Contributing

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

CONTRIBUTING

License

MIT

svg-inline-loader

This Webpack loader inlines SVG as module. If you use Adobe suite or Sketch to export SVGs, you will get auto-generated, unneeded crusts. This loader removes it for you, too.

Install

npm install svg-inline-loader --save-dev

Configuration

Simply add configuration object to module.loaders like this.

    {
        test: /\.svg$/,
        loader: 'svg-inline-loader'
    }

warning: You should configure this loader only once via module.loaders or require('!...'). See #15 for detail.

Query Options

`removeTags: boolean`

Removes specified tags and its children. You can specify tags by setting removingTags query array.

default: removeTags: false

`removingTags: [...string]`

warning: this won't work unless you specify removeTags: true

default: removingTags: ['title', 'desc', 'defs', 'style']

`warnTags: [...string]`

warns about tags, ex: ['desc', 'defs', 'style']

default: warnTags: []

`removeSVGTagAttrs: boolean`

Removes width and height attributes from <svg />.

default: removeSVGTagAttrs: true

`removingTagAttrs: [...string]`

Removes attributes from inside the <svg />.

default: removingTagAttrs: []

`warnTagAttrs: [...string]`

Warns to console about attributes from inside the <svg />.

default: warnTagAttrs: []

`classPrefix: boolean || string`

Adds a prefix to class names to avoid collision across svg files.

default: classPrefix: false

`idPrefix: boolean || string`

Adds a prefix to ids to avoid collision across svg files.

default: idPrefix: false

Example Usage

// Using default hashed prefix (__[hash:base64:7]__)
var logoTwo = require('svg-inline-loader?classPrefix!./logo_two.svg');

// Using custom string
var logoOne = require('svg-inline-loader?classPrefix=my-prefix-!./logo_one.svg');

// Using custom string and hash
var logoThree = require('svg-inline-loader?classPrefix=__prefix-[sha512:hash:hex:5]__!./logo_three.svg');

See loader-utils for hash options.

Preferred usage is via a module.loaders:

    {
        test: /\.svg$/,
        loader: 'svg-inline-loader?classPrefix'
    }

Maintainers

Juho Vepsäläinen

Joshua Wiens

Kees Kluskens

Sean Larkin

thread-loader

Runs the following loaders in a worker pool.

Install

npm install --save-dev thread-loader

Usage

Put this loader in front of other loaders. The following loaders run in a worker pool.

Loaders running in a worker pool are limited. Examples:

Loaders cannot emit files.
Loaders cannot use custom loader API (i. e. by plugins).
Loaders cannot access the webpack options.

Each worker is a separate node.js process, which has an overhead of ~600ms. There is also an overhead of inter-process communication.

Use this loader only for expensive operations!

Examples

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        include: path.resolve("src"),
        use: [
          "thread-loader",
          // your expensive loader (e.g babel-loader)
        ]
      }
    ]
  }
}

with options

use: [
  {
    loader: "thread-loader",
    // loaders with equal options will share worker pools
    options: {
      // the number of spawned workers, defaults to (number of cpus - 1) or
      // fallback to 1 when require('os').cpus() is undefined
      workers: 2,

      // number of jobs a worker processes in parallel
      // defaults to 20
      workerParallelJobs: 50,

      // additional node.js arguments
      workerNodeArgs: ['--max-old-space-size=1024'],

      // Allow to respawn a dead worker pool
      // respawning slows down the entire compilation
      // and should be set to false for development
      poolRespawn: false,

      // timeout for killing the worker processes when idle
      // defaults to 500 (ms)
      // can be set to Infinity for watching builds to keep workers alive
      poolTimeout: 2000,

      // number of jobs the poll distributes to the workers
      // defaults to 200
      // decrease of less efficient but more fair distribution
      poolParallelJobs: 50,

      // name of the pool
      // can be used to create different pools with elsewise identical options
      name: "my-pool"
    }
  },
  // your expensive loader (e.g babel-loader)
]

prewarming

To prevent the high delay when booting workers it possible to warmup the worker pool.

This boots the max number of workers in the pool and loads specified modules into the node.js module cache.

const threadLoader = require('thread-loader');

threadLoader.warmup({
  // pool options, like passed to loader options
  // must match loader options to boot the correct pool
}, [
  // modules to load
  // can be any module, i. e.
  'babel-loader',
  'babel-preset-es2015',
  'sass-loader',
]);

Maintainers

sokra

transform-loader

A browserify transformation loader for webpack.

This loader allows use of browserify transforms via a webpack loader.

Getting Started

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

$ npm install transform-loader --save-dev

Note: We're using the coffeeify tranform for these examples.

Then invoke the loader through a require like so:

const thing = require('!transform-loader?coffeeify!widget/thing');

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

// entry.js
import thing from 'widget/thing';

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.coffee?$/,
        loader: `transform-loader?coffeeify`,
        // options: {...}
      },
    ],
  },
};

And run webpack via your preferred method.

QueryString Options

When using the loader via a require query string you may specify one of two types; a loader name, or a function index.

Type: String

The name of the browserify transform you wish to use.

Note: You must install the correct transform manually. Webpack nor this loader will do that for you.

Type: Number

The index of a function contained within options.transforms which to use to transform the target file(s).

Options

`transforms`

Type: Array[Function] Default: undefined

An array of functions that can be used to transform a given file matching the configured loader test. For example:

// entry.js
const thing = require('widget/thing');

// webpack.config.js
const through = require('through2');

module.exports = {
  module: {
    rules: [
      {
        test: /\.ext$/,
        // NOTE: we've specified an index of 0, which will use the `transform`
        //       function in `transforms` below.
        loader: 'transform-loader?0',
        options: {
          transforms: [
            function transform() {
              return through(
                (buffer) => {
                  const result = buffer
                    .split('')
                    .map((chunk) =>
                      String.fromCharCode(127 - chunk.charCodeAt(0))
                    );
                  return this.queue(result).join('');
                },
                () => this.queue(null)
              );
            },
          ],
        },
      },
    ],
  },
};

Contributing

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

CONTRIBUTING

License

MIT

url-loader

A loader for webpack which transforms files into base64 URIs.

Getting Started

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

$ npm install url-loader --save-dev

url-loader works like file-loader, but can return a DataURL if the file is smaller than a byte limit.

index.js

import img from './image.png';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 8192,
            },
          },
        ],
      },
    ],
  },
};

And run webpack via your preferred method.

Options

Name	Type	Default	Description
Name Type Default Description `limit` `{Boolean\\|Number\\|String}`	`{Boolean\\|Number\\|String}`	`true`	Specifying the maximum size of a file in bytes.
Name Type Default Description `mimetype` `{Boolean\\|String}`	`{Boolean\\|String}`	based from mime-types	Sets the MIME type for the file to be transformed.
Name Type Default Description `encoding` `{Boolean\\|String}`	`{Boolean\\|String}`	`base64`	Specify the encoding which the file will be inlined with.
Name Type Default Description `generator` `{Function}`	`{Function}`	`() => type/subtype;encoding,base64_data`	You can create you own custom implementation for encoding data.
Name Type Default Description `fallback` `{String}`	`{String}`	`file-loader`	Specifies an alternative loader to use when a target file's size exceeds the limit.
Name Type Default Description `esModule` `{Boolean}`	`{Boolean}`	`true`	Use ES modules syntax.

`limit`

Type: Boolean|Number|String Default: undefined

The limit can be specified via loader options and defaults to no limit.

`Boolean`

Enable or disable transform files into base64.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: false,
            },
          },
        ],
      },
    ],
  },
};

`Number|String`

A Number or String specifying the maximum size of a file in bytes. If the file size is equal or greater than the limit file-loader will be used (by default) and all query parameters are passed to it.

Using an alternative to file-loader is enabled via the fallback option.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 8192,
            },
          },
        ],
      },
    ],
  },
};

`mimetype`

Type: Boolean|String Default: based from mime-types

Specify the mimetype which the file will be inlined with. If unspecified the mimetype value will be used from mime-types.

`Boolean`

The true value allows to generation the mimetype part from mime-types. The false value removes the mediatype part from a Data URL (if omitted, defaults to text/plain;charset=US-ASCII).

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              mimetype: false,
            },
          },
        ],
      },
    ],
  },
};

`String`

Sets the MIME type for the file to be transformed.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              mimetype: 'image/png',
            },
          },
        ],
      },
    ],
  },
};

`encoding`

Type: Boolean|String Default: base64

Specify the encoding which the file will be inlined with. If unspecified the encoding will be base64.

`Boolean`

If you don't want to use any encoding you can set encoding to false however if you set it to true it will use the default encoding base64.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              encoding: false,
            },
          },
        ],
      },
    ],
  },
};

`String`

It supports Node.js Buffers and Character Encodings which are ["utf8","utf16le","latin1","base64","hex","ascii","binary","ucs2"].

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              encoding: 'utf8',
            },
          },
        ],
      },
    ],
  },
};

`generator`

Type: Function Default: (mimetype, encoding, content, resourcePath) => mimetype;encoding,base64_content

You can create you own custom implementation for encoding data.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|html)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              // The `mimetype` and `encoding` arguments will be obtained from your options
              // The `resourcePath` argument is path to file.
              generator: (content, mimetype, encoding, resourcePath) => {
                if (/\.html$/i.test(resourcePath)) {
                  return `data:${mimetype},${content.toString()}`;
                }

                return `data:${mimetype}${
                  encoding ? `;${encoding}` : ''
                },${content.toString(encoding)}`;
              },
            },
          },
        ],
      },
    ],
  },
};

`fallback`

Type: String Default: 'file-loader'

Specifies an alternative loader to use when a target file's size exceeds the limit set in the limit option.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              fallback: require.resolve('responsive-loader'),
            },
          },
        ],
      },
    ],
  },
};

The fallback loader will receive the same configuration options as url-loader.

For example, to set the quality option of a responsive-loader above use:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              fallback: require.resolve('responsive-loader'),
              quality: 85,
            },
          },
        ],
      },
    ],
  },
};

`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: 'url-loader',
            options: {
              esModule: false,
            },
          },
        ],
      },
    ],
  },
};

Examples

SVG

SVG can be compressed into a more compact output, avoiding base64. You can read about it more here. You can do it using mini-svg-data-uri package.

webpack.config.js

const svgToMiniDataURI = require('mini-svg-data-uri');

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              generator: (content) => svgToMiniDataURI(content.toString()),
            },
          },
        ],
      },
    ],
  },
};

Contributing

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

CONTRIBUTING

License

MIT

val-loader

A webpack loader which executes a given module, and returns the result of the execution at build-time, when the module is required in the bundle. In this way, the loader changes a module from code to a result.

Another way to view val-loader, is that it allows a user a way to make their own custom loader logic, without having to write a custom loader.

The target module is called with two arguments: (options, loaderContext)

options: The loader options (for instance provided in the webpack config. See the example below).
loaderContext: The loader context.

Getting Started

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

$ npm install val-loader --save-dev

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

target-file.js

module.exports = (options, loaderContext) => {
  return { code: 'module.exports = 42;' };
};

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /target-file.js$/,
        use: [
          {
            loader: `val-loader`,
          },
        ],
      },
    ],
  },
};

src/entry.js

const answer = require('target-file');

And run webpack via your preferred method.

Return Object Properties

Targeted modules of this loader must export a Function that returns an object, or a Promise resolving an object (e.g. async function), containing a code property at a minimum, but can contain any number of additional properties.

`code`

Type: String|Buffer Default: undefined Required

Code passed along to webpack or the next loader that will replace the module.

`sourceMap`

Type: Object Default: undefined

A source map passed along to webpack or the next loader.

`ast`

Type: Array[Object] Default: undefined

An Abstract Syntax Tree that will be passed to the next loader. Useful to speed up the build time if the next loader uses the same AST.

`dependencies`

Type: Array[String] Default: []

An array of absolute, native paths to file dependencies that should be watched by webpack for changes.

Dependencies can also be added using loaderContext.addDependency(file: string).

`contextDependencies`

Type: Array[String] Default: []

An array of absolute, native paths to directory dependencies that should be watched by webpack for changes.

Context dependencies can also be added using loaderContext.addContextDependency(directory: string).

`cacheable`

Type: Boolean Default: false

If true, specifies that the code can be re-used in watch mode if none of the dependencies have changed.

Examples

Simple

In this example the loader is configured to operator on a file name of years-in-ms.js, execute the code, and store the result in the bundle as the result of the execution. This example passes years as an option, which corresponds to the years parameter in the target module exported function:

years-in-ms.js

module.exports = function yearsInMs({ years }) {
  const value = years * 365 * 24 * 60 * 60 * 1000;

  // NOTE: this return value will replace the module in the bundle
  return {
    cacheable: true,
    code: 'module.exports = ' + value,
  };
};

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: require.resolve('src/years-in-ms.js'),
        use: [
          {
            loader: 'val-loader',
            options: {
              years: 10,
            },
          },
        ],
      },
    ],
  },
};

In the bundle, requiring the module then returns:

import tenYearsMs from 'years-in-ms';

console.log(tenYearsMs); // 315360000000

Modernizr

Example shows how to build modernizr.

entry.js

import modenizr from './modernizr.js';

modernizr.js

const modernizr = require('modernizr');

module.exports = function (options) {
  return new Promise(function (resolve) {
    // It is impossible to throw an error because modernizr causes the process.exit(1)
    modernizr.build(options, function (output) {
      resolve({
        cacheable: true,
        code: `var modernizr; var hadGlobal = 'Modernizr' in window; var oldGlobal = window.Modernizr; ${output} modernizr = window.Modernizr; if (hadGlobal) { window.Modernizr = oldGlobal; } else { delete window.Modernizr; } export default modernizr;`,
      });
    });
  });
};

webpack.config.js

const path = require('path');
module.exports = {
  module: {
    rules: [
      {
        test: path.resolve(__dirname, 'src', 'modernizr.js'),
        use: [
          {
            loader: 'val-loader',
            options: {
              minify: false,
              options: ['setClasses'],
              'feature-detects': [
                'test/css/flexbox',
                'test/es6/promises',
                'test/serviceworker',
              ],
            },
          },
        ],
      },
    ],
  },
};

Figlet

Example shows how to build figlet.

entry.js

import { default as figlet } from './figlet.js';

console.log(figlet);

figlet.js

const figlet = require('figlet');

function wrapOutput(output, config) {
  let figletOutput = '';

  if (config.textBefore) {
    figletOutput += encodeURI(`${config.textBefore}\n`);
  }

  output.split('\n').forEach((line) => {
    figletOutput += encodeURI(`${line}\n`);
  });

  if (config.textAfter) {
    figletOutput += encodeURI(`${config.textAfter}\n`);
  }

  return `module.exports = decodeURI("${figletOutput}");`;
}

module.exports = function (options) {
  const defaultConfig = {
    fontOptions: {
      font: 'ANSI Shadow',
      horizontalLayout: 'default',
      kerning: 'default',
      verticalLayout: 'default',
    },
    text: 'FIGLET-LOADER',
    textAfter: null,
    textBefore: null,
  };

  const config = Object.assign({}, defaultConfig, options);

  return new Promise(function (resolve, reject) {
    figlet.text(config.text, config.fontOptions, (error, output) => {
      if (error) {
        return reject(error);
      }

      resolve({
        cacheable: true,
        code: 'module.exports = ' + wrapOutput(output, config),
      });
    });
  });
};

webpack.config.js

const path = require('path');
module.exports = {
  module: {
    rules: [
      {
        test: path.resolve(__dirname, 'src', 'figlet.js'),
        use: [
          {
            loader: 'val-loader',
            options: {
              text: 'FIGLET',
            },
          },
        ],
      },
    ],
  },
};

Contributing

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

CONTRIBUTING

License

MIT

worker-loader

worker loader module for webpack

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install worker-loader --save-dev

Inlined

// App.js
import Worker from 'worker-loader!./Worker.js';

Config

// webpack.config.js
{
  module: {
    rules: [
      {
        test: /\.worker\.js$/,
        use: { loader: 'worker-loader' }
      }
    ]
  }
}

// App.js
import Worker from './file.worker.js';

const worker = new Worker();

worker.postMessage({ a: 1 });
worker.onmessage = function (event) {};

worker.addEventListener("message", function (event) {});

And run webpack via your preferred method.

Options

`fallback`

Type: Boolean Default: false

Require a fallback for non-worker supporting environments

// webpack.config.js
{
  loader: 'worker-loader',
  options: { fallback: false }
}

`inline`

Type: Boolean Default: false

You can also inline the worker as a BLOB with the inline parameter

// webpack.config.js
{
  loader: 'worker-loader',
  options: { inline: true }
}

Note: Inline mode will also create chunks for browsers without support for inline workers, to disable this behavior just set fallback parameter as false.

// webpack.config.js
{
  loader: 'worker-loader',
  options: { inline: true, fallback: false }
}

`name`

Type: String Default: [hash].worker.js

To set a custom name for the output script, use the name parameter. The name may contain the string [hash], which will be replaced with a content dependent hash for caching purposes. When using name alone [hash] is omitted.

// webpack.config.js
{
  loader: 'worker-loader',
  options: { name: 'WorkerName.[hash].js' }
}

publicPath

Type: String Default: null

Overrides the path from which worker scripts are downloaded. If not specified, the same public path used for other webpack assets is used.

// webpack.config.js
{
  loader: 'worker-loader',
  options: { publicPath: '/scripts/workers/' }
}

Examples

The worker file can import dependencies just like any other file:

// Worker.js
const _ = require('lodash')

const obj = { foo: 'foo' }

_.has(obj, 'foo')

// Post data to parent thread
self.postMessage({ foo: 'foo' })

// Respond to message from parent thread
self.addEventListener('message', (event) => console.log(event))

Integrating with ES2015 Modules

Note: You can even use ES2015 Modules if you have the babel-loader configured.

// Worker.js
import _ from 'lodash'

const obj = { foo: 'foo' }

_.has(obj, 'foo')

// Post data to parent thread
self.postMessage({ foo: 'foo' })

// Respond to message from parent thread
self.addEventListener('message', (event) => console.log(event))

Integrating with TypeScript

To integrate with TypeScript, you will need to define a custom module for the exports of your worker

// typings/custom.d.ts
declare module "worker-loader!*" {
  class WebpackWorker extends Worker {
    constructor();
  }

  export default WebpackWorker;
}

// Worker.ts
const ctx: Worker = self as any;

// Post data to parent thread
ctx.postMessage({ foo: "foo" });

// Respond to message from parent thread
ctx.addEventListener("message", (event) => console.log(event));

// App.ts
import Worker from "worker-loader!./Worker";

const worker = new Worker();

worker.postMessage({ a: 1 });
worker.onmessage = (event) => {};

worker.addEventListener("message", (event) => {});

Cross-Origin Policy

WebWorkers are restricted by a same-origin policy, so if your webpack assets are not being served from the same origin as your application, their download may be blocked by your browser. This scenario can commonly occur if you are hosting your assets under a CDN domain. Even downloads from the webpack-dev-server could be blocked. There are two workarounds:

Firstly, you can inline the worker as a blob instead of downloading it as an external script via the inline parameter

// App.js
import Worker from './file.worker.js';

// webpack.config.js
{
  loader: 'worker-loader',
  options: { inline: true }
}

Secondly, you may override the base download URL for your worker script via the publicPath option

// App.js
// This will cause the worker to be downloaded from `/workers/file.worker.js`
import Worker from './file.worker.js';

// webpack.config.js
{
  loader: 'worker-loader',
  options: { publicPath: '/workers/' }
}

Contributing

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

CONTRIBUTING

License

MIT

yaml-frontmatter-loader

YAML frontmatter loader for webpack. Converts YAML in files to JSON.

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

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

$ npm install yaml-frontmatter-loader --save-dev

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

const json = require('yaml-frontmatter-loader!./file.md');
// => returns file.md as javascript object

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
         test: /\.md$/,
         use: [ 'json-loader', 'yaml-frontmatter-loader' ]
      }
    ]
  }
}

And run webpack via your preferred method.

License

MIT

Loaders

webpack enables use of loaders to preprocess files. This allows you to bundle any static resource way beyond JavaScript. You can easily write your own loaders using Node.js.

Loaders are activated by using loadername! prefixes in require() statements, or are automatically applied via regex from your webpack configuration – see configuration.

Files

raw-loader Loads raw content of a file (utf-8)
val-loader Executes code as module and consider exports as JS code
url-loader Works like the file loader, but can return a data URL if the file is smaller than a limit
file-loader Emits the file into the output folder and returns the (relative) URL
ref-loader Create dependencies between any files manually

JSON

json-loader Loads a JSON file (included by default)
json5-loader Loads and transpiles a JSON 5 file
cson-loader Loads and transpiles a CSON file

Transpiling

script-loader Executes a JavaScript file once in global context (like in script tag), requires are not parsed
babel-loader Loads ES2015+ code and transpiles to ES5 using Babel
buble-loader Loads ES2015+ code and transpiles to ES5 using Bublé
traceur-loader Loads ES2015+ code and transpiles to ES5 using Traceur
ts-loader or awesome-typescript-loader Loads TypeScript 2.0+ like JavaScript
coffee-loader Loads CoffeeScript like JavaScript
fengari-loader Loads Lua code using fengari
elm-webpack-loader Loads Elm like JavaScript

Templating

html-loader Exports HTML as string, require references to static resources
pug-loader Loads Pug and Jade templates and returns a function
markdown-loader Compiles Markdown to HTML
react-markdown-loader Compiles Markdown to a React Component using the markdown-parse parser
posthtml-loader Loads and transforms a HTML file using PostHTML
handlebars-loader Compiles Handlebars to HTML
markup-inline-loader Inline SVG/MathML files to HTML. It’s useful when applying icon font or applying CSS animation to SVG.
twig-loader Compiles Twig templates and returns a function

Styling

style-loader Add exports of a module as style to DOM
css-loader Loads CSS file with resolved imports and returns CSS code
less-loader Loads and compiles a LESS file
sass-loader Loads and compiles a SASS/SCSS file
postcss-loader Loads and transforms a CSS/SSS file using PostCSS
stylus-loader Loads and compiles a Stylus file

Linting && Testing

mocha-loader Tests with mocha (Browser/NodeJS)
eslint-loader PreLoader for linting code using ESLint
jshint-loader PreLoader for linting code using JSHint
jscs-loader PreLoader for code style checking using JSCS
coverjs-loader PreLoader to determine the testing coverage using CoverJS

Frameworks

vue-loader Loads and compiles Vue Components
polymer-loader Process HTML & CSS with preprocessor of choice and require() Web Components like first-class modules
angular2-template-loader Loads and compiles Angular Components

Awesome

For more third-party loaders, see the list from awesome-webpack.

Contributors

webpack

Printable

babel-loader

Install

Usage

Options

Troubleshooting

babel-loader is slow!

Babel is injecting helpers into each file and bloating my code!

NOTE: transform-runtime & custom polyfills (e.g. Promise library)

The Node.js API for babel has been moved to babel-core.

Customize config based on webpack target

Customized Loader

Example

customOptions(options: Object): { custom: Object, loader: Object }

config(cfg: PartialConfig): Object

result(result: Result): Result

License

bundle-loader

Install

Usage

Options

lazy

name

Examples

Maintainers

cache-loader

Getting Started

Options

Examples

Basic

Database Integration

Contributing

License

coffee-loader

Install

Usage

Configuration (recommended)

Options

Sourcemaps

Maintainer

coffee-redux-loader

Install

Usage

Maintainers

coverjs-loader

Usage

License

css-loader

Getting Started

toString

Options

url

Boolean

Function

import

Boolean

Function

modules

Features

Scope

Composing

Importing

Values

Boolean

String

Object

auto

Boolean

RegExp

mode

String

Function

exportGlobals

localIdentName

context

hashPrefix

getLocalIdent

localIdentRegExp

sourceMap

importLoaders

The Node.js API for `babel` has been moved to `babel-core`.

`customOptions(options: Object): { custom: Object, loader: Object }`

`config(cfg: PartialConfig): Object`

`result(result: Result): Result`

`lazy`

`name`

`Configuration (recommended)`

`Sourcemaps`

`toString`

`url`

`Boolean`

`Function`

`import`

`Boolean`

`Function`

`modules`

`Features`

`Scope`

`Composing`

`Importing`

`Values`

`Boolean`

`String`

`Object`

`auto`

`Boolean`

`RegExp`

`mode`

`String`

`Function`

`exportGlobals`

`localIdentName`

`context`

`hashPrefix`

`getLocalIdent`

`localIdentRegExp`

`sourceMap`

`importLoaders`

`localsConvention`

`onlyLocals`

`esModule`

`cache`

`eslintPath`

`fix`

`formatter`

`emitError`

`emitWarning`

`failOnError`

`failOnWarning`

`quiet`

`outputReport`

Defining `configFile` or using `eslint -c path/.eslintrc`

`name`

`String`

`Function`

`outputPath`

`String`

`Function`

`publicPath`

`String`

`Function`

`postTransformPublicPath`

`context`