Loader context#

The loader context represents the properties that are available inside of a loader assigned to the this property.

this.addContextDependency()#

• Type:

function addContextDependency(directory: string): void;

Add the directory as a dependency for the loader results so that any changes to the files in the directory can be listened to.

For example, adding src/static as a dependency. When the files in the src/static directory change, it will trigger a rebuild.

const path = require('node:path');

module.exports = function loader(source) {
  this.addContextDependency(path.resolve(this.rootContext, 'src/static'));
  return source;
};

this.addDependency()#

• Type:

function addDependency(file: string): void;

Add a file as a dependency on the loader results so that any changes to them can be listened to. For example, sass-loader, less-loader use this trick to recompile when the imported style files change.

const path = require('node:path');

module.exports = function loader(source) {
  this.addDependency(path.resolve(this.rootContext, 'src/styles/foo.scss'));
  return source;
};

this.addMissingDependency()#

• Type:

function addMissingDependency(file: string): void;

Add a currently non-existent file as a dependency of the loader result, so that its creation and any changes can be listened. For example, when a new file is created at that path, it will trigger a rebuild.

const path = require('node:path');

module.exports = function loader(source) {
  this.addMissingDependency(
    path.resolve(this.rootContext, 'src/dynamic-file.json'),
  );
  return source;
};

this.async()#

• Type: () => LoaderContextCallback

Tells Rspack that this loader will be called asynchronously. Returns this.callback.

this.cacheable()#

• Type:

function cacheable(flag: boolean = true): void;

A function that sets the cacheable flag:

By default, the processing results of the loader are marked as cacheable. Calling this method and passing false turns off the loader's ability to cache processing results.

this.callback()#

• Type:

function callback(
  err: Error | null,
  content: string | Buffer,
  sourceMap?: SourceMap,
  meta?: any,
): void;

A function that can be called synchronously or asynchronously in order to return multiple results. The expected arguments are:

1. The first parameter must be Error or null, which marks the current module as a compilation failure.
2. The second argument is a string or Buffer, which indicates the contents of the file after the module has been processed by the loader.
3. The third parameter is a source map that can be processed by the loader.
4. The fourth parameter is ignored by Rspack and can be anything (e.g. some metadata).

this.clearDependencies()#

• Type:

function clearDependencies(): void;

Removes all dependencies of the loader result.

this.context#

• Type: string | null

The directory path of the currently processed module, which changes with the location of each processed module.

For example, if the loader is processing /project/src/components/Button.js, then the value of this.context would be /project/src/components.

module.exports = function loader(source) {
  console.log(this.context); // '/project/src/components'
  return source;
};

If the module being processed is not from the file system, such as a virtual module, then the value of this.context is null.

this.data#

• Type: unknown

A data object shared between the pitch and the normal phase.

this.dependency()#

• Type:

function dependency(file: string): void;

Alias of this.addDependency().

this.emitError()#

• Type:

function emitError(error: Error): void;

Emit an error. Unlike throw and this.callback(err) in the loader, it does not mark the current module as a compilation failure, it just adds an error to Rspack's Compilation and displays it on the command line at the end of this compilation.

this.emitWarning()#

• Type:

function emitWarning(warning: Error): void;

Emit a warning.

this.emitFile()#

• Type:

function emitFile(
  name: string,
  content: string | Buffer,
  sourceMap?: string,
  assetInfo?: JsAssetInfo,
): void;

Emit a new file. This method allows you to create new files during the loader execution.

• Basic example:

module.exports = function loader(source) {
  // Emit a new file that will be output as `foo.js` in the output directory
  this.emitFile('foo.js', 'console.log("Hello, world!");');
  return source;
};

• Example with asset info:

module.exports = function loader(source) {
  this.emitFile(
    'foo.js',
    'console.log("Hello, world!");',
    undefined, // no sourcemap
    {
      sourceFilename: this.resourcePath,
    },
  );

  return source;
};

this.getOptions()#

• Type:

function getOptions(schema?: any): OptionsType;

Get the options passed in by the loader's user.

For example:

module.exports = {
  module: {
    rules: [
      {
        test: /\.txt$/,
        use: {
          loader: './my-loader.js',
          options: {
            foo: 'bar',
          },
        },
      },
    ],
  },
};

In my-loader.js get the options passed in:

module.exports = function myLoader(source) {
  const options = this.getOptions();
  console.log(options); // { foo: 'bar' }
  return source;
};

In TypeScript, you can set the options type through the generic of LoaderContext.

import type { LoaderContext } from '@rspack/core';

type MyLoaderOptions = {
  foo: string;
};

export default function myLoader(
  this: LoaderContext<MyLoaderOptions>,
  source: string,
) {
  const options = this.getOptions();
  console.log(options); // { foo: 'bar' }
  return source;
}

this.getResolve()#

• Type:

function getResolve(options: ResolveOptions): resolve;

Create a resolver like this.resolve.

this.importModule()#

• Type:

interface ImportModuleOptions {
  /**
   * Specify a layer in which this module is placed/compiled
   */
  layer?: string;
  /**
   * The public path used for the built modules
   */
  publicPath?: PublicPath;
  /**
   * Target base uri
   */
  baseUri?: string;
}

// with callback
function importModule<T = any>(
  request: string,
  options: ImportModuleOptions | undefined,
  callback: (err?: null | Error, exports?: T) => any,
): void;
// without callback, return Promise
function importModule<T = any>(
  request: string,
  options?: ImportModuleOptions,
): Promise<T>;

Compile and execute a module at the build time. This is an alternative lightweight solution for the child compiler.

importModule will return a Promise if no callback is provided.

const path = require('node:path');

module.exports = async function loader(source) {
  const modulePath = path.resolve(this.rootContext, 'some-module.ts');
  const moduleExports = await this.importModule(modulePath, {
    // optional options
  });

  const result = someProcessing(source, moduleExports);
  return result;
};

Or you can pass a callback to it.

const path = require('node:path');

module.exports = function loader(source) {
  const callback = this.async();
  const modulePath = path.resolve(this.rootContext, 'some-module.ts');

  this.importModule(
    modulePath,
    // optional options
    undefined,
    (err, moduleExports) => {
      if (err) {
        return callback(err);
      }

      const result = someProcessing(source, moduleExports);
      callback(null, result);
    },
  );
};

this.resolve()#

• Type:

function resolve(
  context: string,
  request: string,
  callback: (err: Error | null, result: string) => void,
): void;

Resolve a module specifier.

• context must be the absolute path to a directory. This directory is used as the starting location for resolving.
• request is the module specifier to be resolved.
• callback is a callback function that gives the resolved path.

this.mode#

• Type: Mode

The value of mode is read when Rspack is run.

The possible values are: 'production', 'development', 'none'

module.exports = function loader(source) {
  console.log(this.mode); // 'production' or other values
  return source;
};

this.target#

• Type: Target

The value of target is read when Rspack is run.

module.exports = function loader(source) {
  console.log(this.target); // 'web' or other values
  return source;
};

this.resource#

• Type: string

The path string of the current module. For example '/abc/resource.js?query#hash'.

module.exports = function loader(source) {
  console.log(this.resource); // '/abc/resource.js?query#hash'
  return source;
};

this.resourcePath#

• Type: string

The path string of the current module, excluding the query and fragment parameters. For example '/abc/resource.js?query#hash' in '/abc/resource.js'.

module.exports = function loader(source) {
  console.log(this.resourcePath); // '/abc/resource.js'
  return source;
};

this.resourceQuery#

• Type: string

The query parameter for the path string of the current module. For example '?query' in '/abc/resource.js?query#hash'.

module.exports = function loader(source) {
  console.log(this.resourceQuery); // '?query'
  return source;
};

this.resourceFragment#

• Type: string

The fragment parameter of the current module's path string. For example '#hash' in '/abc/resource.js?query#hash'.

module.exports = function loader(source) {
  console.log(this.resourceFragment); // '#hash'
  return source;
};

this.rootContext#

• Type: string

The base path configured in Rspack config via context.

module.exports = function loader(source) {
  console.log(this.rootContext); // /path/to/project
  return source;
};

this.sourceMap#

• Type: boolean

Whether a source map should be generated.

this.getLogger()#

• Type:

function getLogger(name?: string): Logger;

Get the logger of this compilation, through which messages can be logged.