import { ApiMeta, Stability } from '@components/ApiMeta'; import WebpackLicense from '@components/WebpackLicense';

Loader context

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

this.addBuildDependency()

• Type:

function addBuildDependency(file: string): void;

Add a file as a build dependency of the loader result. Build dependencies are used to invalidate the persistent cache when they change.

Use this for files that affect a loader's behavior or transformation result, such as a loader configuration file.

import path from 'node:path';

export default function loader(source) {
  this.addBuildDependency(
    path.resolve(this.rootContext, 'custom-loader.config.js'),
  );
  return source;
}

:::tip this.addBuildDependency() does not make the file a watch dependency. If changes to the file should trigger a rebuild in watch mode, also call this.addDependency(). :::

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.

import path from 'node:path';

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

import path from 'node:path';

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

import path from 'node:path';

export default 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;

By default, the final build result produced for the current module by the entire loader chain is cacheable. Calling this.cacheable(false) marks that result as non-cacheable.

Once a loader has called this.cacheable(false), subsequent loaders cannot make the result cacheable again by calling this.cacheable(true) or this.cacheable(). Only this.clearDependencies() resets this state.

export default function loader(source) {
  this.cacheable(false);
  return source;
}

this.callback()

• Type:

interface AdditionalData {
  [index: string]: any;
}

function callback(
  err?: Error | null,
  content?: string | Buffer,
  sourceMap?: string | Rspack.RawSourceMap,
  additionalData?: AdditionalData,
): void;

Call this.callback() to return a loader's results, either synchronously or asynchronously. Its arguments are:

1. err: An Error when the loader fails, or null or undefined when it succeeds.
2. content: The transformed module content as a string or Buffer. It can be omitted when reporting an error.
3. sourceMap: An optional source map as a string or Rspack.RawSourceMap.
4. additionalData: Optional additional data. Rspack passes it as the third argument to the next loader in the chain.

See Sync loader for more details.

:::warning In case this function is called, you should return undefined to avoid ambiguous loader results.

The content, sourceMap, and additionalData values are passed to the next loader in the chain. :::

this.clearDependencies()

• Type:

function clearDependencies(): void;

Clears all file dependencies, context dependencies, and missing dependencies collected by the loader chain. Build dependencies are not cleared. This also resets cacheable to true, overriding any earlier call to this.cacheable(false).

Only use this method when the current loader will register every dependency required by the final 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.

export default function loader(source) {
  console.log(this.context); // '/project/src/components'
  return source;
}

If the current module has no resource path, the value of this.context is null.

this.loaderIndex

• Type: number

The index in the loaders array of the current loader.

this.loaders

• Type: LoaderObject[]

this.loaders contains all loaders applied to the current module. Each item provides information such as the resolved request, path, query, and options.

During the pitch phase, you can modify the array to adjust the loader chain. Use this.loaderIndex to locate the current loader.

export function pitch() {
  const currentLoader = this.loaders[this.loaderIndex];
  console.log(currentLoader.request);
}

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.

::: info 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.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 an error or warning diagnostic. Supports the display of module paths, source code snippets, and line/column numbers.

::: info Unlike throw and this.callback(err) in a loader, it does not mark the current module as a compilation failure. It adds an error or warning to Rspack's Compilation according to severity, then displays it on the command line at the end of the compilation. :::

• Basic example:

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

/** @type {import("@rspack/core").LoaderDefinition} */
export default 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.mjs!)
  × ModuleError: `React` is not defined

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

• Printing code snippet:

/** @type {import("@rspack/core").LoaderDefinition} */
export default 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:

export default 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:

export default 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.getContextDependencies()

• Type:

function getContextDependencies(): string[];

Returns all directories the loader currently watches as context dependencies, including directories added with this.addContextDependency().

export default function loader(source) {
  const contextDependencies = this.getContextDependencies();
  console.log(contextDependencies);

  return source;
}

this.getDependencies()

• Type:

function getDependencies(): string[];

Returns all files the loader currently watches as dependencies, including files added with this.addDependency() or this.dependency().

export default function loader(source) {
  const dependencies = this.getDependencies();
  console.log(dependencies);

  return source;
}

this.getMissingDependencies()

• Type:

function getMissingDependencies(): string[];

Returns all paths to files that the loader is watching but that do not exist yet, including paths added with this.addMissingDependency(). Creating one of these files may trigger a rebuild.

export default function loader(source) {
  const missingDependencies = this.getMissingDependencies();
  console.log(missingDependencies);

  return source;
}

Each method returns a new array. Modifying the returned array does not change the dependencies registered by the loader. To remove dependencies from these three lists, use this.clearDependencies().

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.mjs',
          options: {
            foo: 'bar',
          },
        },
      },
    ],
  },
};

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

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

:::tip When a loader is configured with a query string such as loader: './my-loader?s=foo+bar', this.getOptions() parses that string with Node.js querystring.parse(). That means a literal + is decoded as a space, so the result is { s: 'foo bar' }.

If you need a literal plus sign, encode + as %2B or prefer an options object in the loader rule. Use this.query when you need the raw query string. :::

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;
}

:::tip The parameter schema is optional and will not be used in Rspack.

To provide the best performance, Rspack does not perform the schema validation. If your loader requires schema validation, please call schema-utils or other schema validation libraries. :::

this.getResolve()

• Type:

type ResolveFunction = {
  (
    context: string,
    request: string,
    callback: (
      err: Error | null,
      result?: string | false,
      resolveRequest?: ResolveRequest,
    ) => void,
  ): void;
  (context: string, request: string): Promise<string | false | undefined>;
};

function getResolve(options?: ResolveOptions): ResolveFunction;

Creates a resolver like this.resolve(). Pass options to customize the resolver. If no options are provided, it uses the normal resolver without additional options.

The returned resolver supports both callback and Promise forms. When no callback is passed, it returns a Promise.

export default async function loader(source) {
  const resolve = this.getResolve({
    extensions: ['.js', '.json'],
  });
  const result = await resolve(this.context, './dependency');

  console.log(result);
  return source;
}

this.hot

• Type: boolean

Whether HMR is enabled.

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

import path from 'node:path';

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

import path from 'node:path';

export default 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 ?.

Unlike this.getOptions(), the query-string form is not parsed. For example, loader: './my-loader?s=foo+bar' gives this.query === '?s=foo+bar'.

this.remainingRequest

• Type: string

this.remainingRequest consists of the loaders that follow the current loader in the chain and the current resource, joined with !.

For example, consider the following loader chain:

/path/to/loader1.mjs!/path/to/loader2.mjs!/path/to/resource.js

When Rspack runs loader1.mjs, this.remainingRequest is:

/path/to/loader2.mjs!/path/to/resource.js

You can use it to create an inline request without invoking the current loader again. See Inline matchResource for an example.

this.currentRequest

• Type: string

this.currentRequest consists of the current loader, the loaders that follow it in the chain, and the current resource, joined with !.

For example, consider the following loader chain:

/path/to/loader1.mjs!/path/to/loader2.mjs!/path/to/resource.js

When Rspack runs loader2.mjs, this.currentRequest is:

/path/to/loader2.mjs!/path/to/resource.js

this.previousRequest

• Type: string

this.previousRequest consists of the loaders that precede the current loader, joined with !. It does not include the current resource.

For example, consider the following loader chain:

/path/to/loader1.mjs!/path/to/loader2.mjs!/path/to/resource.js

When Rspack runs loader2.mjs, this.previousRequest is:

/path/to/loader1.mjs

this.request

• Type: string

The complete request string, consisting of all loaders and the current resource joined with !.

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

this.resolve()

• Type:

function resolve(
  context: string,
  request: string,
  callback: (
    err: Error | null,
    result?: string | false,
    resolveRequest?: ResolveRequest,
  ) => 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 receives the error, the resolved path (or false when the request is ignored), and optional resolution details.

this.mode

• Type: Mode | undefined

The value of the mode configuration.

The possible values are 'production', 'development', 'none', and undefined. If mode is not configured, this.mode is undefined, even though Rspack applies production-oriented defaults.

export default function loader(source) {
  console.log(this.mode); // 'production', 'development', 'none', or undefined
  return source;
}

this.target

• Type: Target | undefined

By default, this is a simplified target value derived from the target configuration. When possible, Rspack maps the target's capabilities to a value such as 'web', 'node', 'nwjs', or 'electron-main'. Therefore, this.target is not necessarily identical to the original target configuration.

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

this.environment

• Type: Environment

Describes the capabilities supported by the target environment. By default, this is the effective value of output.environment: Rspack infers the capabilities from target, then applies the explicit settings from output.environment.

A loader can use this information to choose syntax supported by the output environment.

export default function loader(source) {
  if (this.environment.optionalChaining) {
    console.log('Optional chaining is supported');
  }

  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.

export default 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'.

export default 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, the value is '/abc/resource.js' for '/abc/resource.js?query#hash'.

export default 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'.

export default 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'.

export default function loader(source) {
  console.log(this.resourceFragment); // '#hash'
  return source;
}

this.rootContext

• Type: string

The base path configured in Rspack config via context.

export default 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

:::warning Please note that using internal Rspack properties like this._compiler and this._compilation will cause your loader to lose its independence.

Ideally, loaders should focus on file transformation logic, with deterministic output for given input, without depending on Rspack's internal state. Relying on these internal objects introduces unpredictable behavior, making testing and maintenance more difficult.

Therefore, it's recommended to consider using these properties only when there are no other alternatives. :::

this._compiler

• Type: Compiler

Access to the current Compiler object of Rspack.

this._compilation

• Type: Compilation

Access to the current Compilation object of Rspack.