#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.

See Async loader for more details.

#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.

module.exports = function loader(source) {
  this.cacheable(false);
  return source;
};

#this.callback()

• Type:

function callback(
  err: Error | null,
  content: string | Buffer,
  sourceMap?: Rspack.RawSourceMap,
  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).

See Sync loader for more details.

#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.loaderIndex

• Type: number

The index in the loaders array of the current loader.

#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.

#this.emitWarning()

• Type:

function emitWarning(warning: Error): void;

Emit a warning.

#this.experiments.emitDiagnostic()

• Type:

interface DiagnosticLocation {
  /** Text for highlighting the location */
  text?: string;
  /** 1-based line */
  line: number;
  /** 0-based column in bytes */
  column: number;
  /** Length in bytes */
  length: number;
}

interface Diagnostic {
  message: string;
  help?: string;
  sourceCode?: string;
  /**
   * Location to the source code.
   * If `sourceCode` is not provided, location will be omitted.
   */
  location?: DiagnosticLocation;
  /**
   * Optional filename to show.
   * If provided, it becomes the `StatsError.file` value in stats.
   */
  file?: string;
  severity: 'error' | 'warning';
}

function emitDiagnostic(diagnostic: Diagnostic): void;

Formats and emits a diagnostic message (error or warning log). Supports the display of module paths, source code snippets and line/column numbers.

• Basic example:

When only message and severity are provided, only the basic module error information will be printed.

/** @type {import("@rspack/core").LoaderDefinition} */
module.exports = function () {
  this.experiments.emitDiagnostic({
    message: '`React` is not defined',
    severity: 'error',
  });
  this.experiments.emitDiagnostic({
    message: '`React` is not defined',
    severity: 'warning',
  });
  return '';
};

This will print:

ERROR in (./loader.js!)
  × ModuleError: `React` is not defined

WARNING in (./loader.js!)
  ⚠ ModuleWarning: `React` is not defined

• Printing code snippet:

/** @type {import("@rspack/core").LoaderDefinition} */
module.exports = function () {
  this.experiments.emitDiagnostic({
    message: '`React` is not defined',
    severity: 'error',
    sourceCode: `<div></div>`,
    location: {
      line: 1,
      column: 1,
      length: 3,
    },
    file: './some-file.js',
  });
  return '';
};

This will print:

ERROR in ./some-file.js
 ./file.js 1:1-4
  × ModuleError: `React` is not defined
   ╭────
 1 │ <div></div>
   ·  ───
   ╰────

Here, ./some-file.js is the value passed to the file field.

#this.emitFile()

• Type:

function emitFile(
  name: string,
  content: string | Buffer,
  sourceMap?: string,
  assetInfo?: AssetInfo,
): 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.fs

• Type: InputFileSystem

Access to the compilation object's inputFileSystem property.

#this.getOptions()

• Type:

function getOptions(schema?: any): OptionsType;

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

For example:

export default {
  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.hot

• Type: boolean

Whether HMR is enabled.

module.exports = function (source) {
  console.log(this.hot); // true if HMR is enabled
  return source;
};

#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.query

• Type: string | OptionsType

The value depends on the loader configuration:

• If the current loader was configured with an options object, this.query will point to that object.
• If the current loader has no options, but was invoked with a query string, this will be a string starting with ?.

#this.request

• Type: string

The module specifier string after being resolved.

For example, if a resource.js is processed by loader1.js and loader2.js, the value of this.request will be /path/to/loader1.js!/path/to/loader2.js!/path/to/resource.js.

#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 current compilation target. Passed from target configuration options.

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

#this.utils

• Type:

type Utils = {
  absolutify: (context: string, request: string) => string;
  contextify: (context: string, request: string) => string;
  createHash: (algorithm?: string) => Hash;
};

Access to the following utilities.

• absolutify: Return a new request string using absolute paths when possible.
• contextify: Return a new request string avoiding absolute paths when possible.
• createHash: Return a new Hash object from provided hash function.

module.exports = function (content) {
  this.utils.contextify(
    this.context,
    this.utils.absolutify(this.context, './index.js'),
  );

  this.utils.absolutify(this.context, this.resourcePath);

  const mainHash = this.utils.createHash(
    this._compilation.outputOptions.hashFunction,
  );
  mainHash.update(content);
  mainHash.digest('hex');

  return content;
};

#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

Tells if source map should be generated.

Since generating source maps can be an expensive task, you should check if source maps are actually requested.

See Handling source maps for more details.

#this.getLogger()

• Type:

function getLogger(name?: string): Logger;

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

#this.version

• Type: number

The version number of the loader API. Currently 2.

This is useful for providing backwards compatibility. Using the version you can specify custom logic or fallbacks for breaking changes.

#Internal properties

#this._compiler

• Type: Compiler

Access to the current Compiler object of Rspack.

#this._compilation

• Type: Compilation

Access to the current Compilation object of Rspack.