Loader Specification

sokra edited this page Nov 2, 2014 · 18 revisions


see http://webpack.github.io/docs/loaders.html!

Loader Specification

require syntax

require("./file.js"); // no loader used
require("loaderA!./file.js"); // "loaderA" is used
     // file.js is process by first-loader, loader2 and loader3 in this order
require("./file.jade"); // some configured extensions automatically use loaders
require("!./file.jade"); // this can be overwritten by a leading "!"
require("./myloader!loaderA/folder/abc!./file.js"); // files and folders possible

with webpack 0.8 queries are added:


Queries can be any string not containing !. They are passed to the loader.


loader "xyz" resolve to the package: (in this order)

  • xyz-vendor-web-loader
  • xyz-vendor-loader
  • xyz-web-loader
  • xyz-loader
  • xyz

And "./abc" as loader resolve to the file: (in this order)

  • abc.vendor-web-loader.js
  • abc.vendor-loader.js
  • abc.web-loader.js
  • abc.loader.js
  • abc.js
  • abc

package.json can contain a field loader which overwrites the used file in a package. Elsewise index is used and resolved like a file (above "./index")

vendor is a module system specific name, in example webpack for webpack.

loader module

A loader module MUST export a function (called loader function).

The loader function will be called by the module system with one or more arguments. The module system provides a this context to the loader function with additional data.

this.request string required the resolved request which results in querying the loader
this.async function() required call it if you offer a asynchron behavior in your loader. It returns a function if the module system supports this. Call the function with (err, arg1, arg2, ...) if you are done. Fallback to synchron behavior if it returns null, false or undefined.
this.callback function() required use this function to return multiple return values from your loader. Call it with (err, arg1, arg2, ...).
this.options object required options of the module system. A loader may claim a member of options for own options.
this.context string optional The path from which this request comes from. Can be used for more resolving.
this.web boolean optional true, if target is a browser
this.filenames string[] optional the files providing the content of the arguments to the loader
this.query string optional the query passed for this loader
this.resourceQuery string optional the query passed for the resource
this.debug boolean optional true, if loader should emit debug info
this.minimize boolean optional true, if loader should minimize its output (except javascript)
this.resolve function(context, path, callback) optional resolves a path in a context and callback is called with (err, absoluteFilename)
this.values optional A loader may write an array into this member which contains the result of execution of its returning javascript code.
this.inputValues array optional if set it contains the this.values of the last loader. Item X should equal to this.exec(argX), but a loader can use it for performance reasons.
this.exec function(code, filenameOfCode) optional Executes javascript code like a module and returns the exports.
this.buffers Buffer[] optional The arguments of the loader as Buffers. This is useful if the file is not a text file.
this.emitFile function(filename, content) optional Emits a file to the output. content may be a Buffer or a string, which is emitted as utf-8.
this.cacheable function(flag = true) optional Flag the output of the loader as cacheable (or not cachable). Loader must call this.dependency() if it has more dependencies that its arguments.
this.dependency function(filename) optional Add a dependency. If the loader is cacheable the cached version will not longer be used if the dependency has changed (timestamp). Additionally it's required for watch mode.
this.clearDependencies function() optional Removes all dependencies from the loader, including arguments.
this.loaderType string optional "loader", "preLoader", or "postLoader". The type of the current loader.
this.currentLoaders string[] optional The list of loaders of the current loader type.
this.loaderIndex number optional The index of the loader currently executed.
this.loaders string[] optional The list of loaderss which are applied to the current file.
this.preLoaders string[] optional The list of preLoaders which are applied to the current file.
this.postLoaders string[] optional The list of postLoaders which are applied to the current file.
more optional A module system may provide more members

loader options

Beside the loader function, a loader can export options to the module system.

module.exports = function(...) { ... };
module.exports.option1 = value1;
module.exports.option2 = value2;


(Boolean) default = false

Flag a loader as separable. This means it can run separate from the module system and other loaders. I. e. in a separate process. A module system may do this for performance reasons.


(Boolean default = false

Like separable but only valid if resolving is allowed in separate process.