loader-runner

4.3.2 verified Sat Apr 25 auth: no javascript

Runs (webpack) loaders as an independent module without webpack itself. Current stable version is 4.3.2, released in 2021 with performance improvements. Minimal release cadence: roughly one version per year. Key differentiator: it allows running loaders in isolation for testing or custom build pipelines. Supports Node.js >=6.11.5 and is ESM/CJS compatible. Lightweight, focuses solely on loader execution logic with hooks for resource processing.

Common errors

error Cannot find module 'loader-runner' ↓

cause Package not installed or incorrect import path.

fix

Run 'npm install loader-runner' and use correct import: 'import { runLoaders } from "loader-runner"'.

error runLoaders is not a function ↓

cause Wrong import style — default import used instead of named import.

fix

Change import to: 'import { runLoaders } from "loader-runner"' or use CommonJS destructuring: 'const { runLoaders } = require("loader-runner")'.

error Callback called twice with rejected promise ↓

cause Loader returns a promise that rejects after calling callback.

fix

Remove callback call when using promise; use only promise resolve/reject.

error TypeError: Cannot read property 'result' of undefined ↓

cause Error occurred but err is null in callback if result is undefined.

fix

Check both err and result in callback; result may be undefined on error.

Warnings

breaking Since v3, the minimum Node.js version is 6. ↓

fix Upgrade Node.js to >=6 or stick to v2 if using older Node.

breaking Since v3, callback can accept undefined as 'no result' in pitching phase, and errors are reported via callback instead of throwing. ↓

fix Update loader code to handle callback(err, undefined) and avoid throwing.

deprecated The old approach of using System.import for loader loading was removed in v3. ↓

fix Use normal require/import for loaders.

gotcha The callback may be called twice with a rejected promise if the loader returns a promise that rejects after the callback is already invoked. ↓

fix Ensure loaders do not call both callback and reject a promise; favor one error handling mechanism.

gotcha Always set resourcePath, resourceQuery and resourceHash to empty string when request is empty (since v4.3.1). ↓

fix If relying on these properties, check that they are empty strings instead of undefined.

gotcha Resource string with '#' must be escaped to avoid misinterpretation (since v4.1.0). ↓

fix Use escape sequences for '#' in resource and loader requests.

Install

npm install loader-runner

yarn add loader-runner

pnpm add loader-runner

Imports

runLoaders
wrong
```
const runLoaders = require('loader-runner')
```
correct
```
import { runLoaders } from 'loader-runner'
```
Default import is not available; use named import. CommonJS works with require('loader-runner').runLoaders, but named import is preferred for ESM.

runLoaders

wrong

const runLoaders = require('loader-runner').default

correct

const { runLoaders } = require('loader-runner')

Destructuring from require is correct. There is no default export.

type LoaderDefinition
```
import type { LoaderDefinition } from 'loader-runner'
```
LoaderDefinition is a TypeScript type exported for loader implementations. Use with 'import type' for type-only usage.

Quickstart

Demonstrates basic usage of runLoaders with a resource, loader configuration, and a callback.

import { runLoaders } from 'loader-runner';
import { readFile } from 'fs';

runLoaders({
  resource: '/path/to/file.txt?query',
  loaders: [
    {
      loader: '/path/to/loader.js',
      options: { minimize: true }
    }
  ],
  context: {},
  readResource: readFile
}, (err, result) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(result.result[0].toString());
  console.log(result.fileDependencies);
});