loader-runner

What is loader-runner?

The loader-runner npm package is designed to run webpack loaders in a node.js environment without requiring the webpack itself. It allows developers to test and run individual loaders, simulating the webpack compilation process. This can be particularly useful for loader development, testing, and debugging.

What are loader-runner's main functionalities?

Running a single loader

This feature allows running a single loader on a specified file. In the code sample, `runLoaders` is used to apply a CSS loader to a CSS file, demonstrating how to process a resource with specific loader configurations.

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

runLoaders({
  resource: 'path/to/file.css',
  loaders: [{ loader: 'path/to/css-loader' }],
  context: { minimize: true },
  readResource: fs.readFile.bind(fs)
}, (err, result) => {
  if(err) {
    return console.error(err);
  }
  console.log(result);
});

Running multiple loaders

This feature demonstrates how to chain multiple loaders, in this case, an ESLint loader followed by a Babel loader, to process a JavaScript file. It showcases the ability to use loader-runner for complex processing involving multiple steps.

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

runLoaders({
  resource: 'path/to/file.js',
  loaders: [
    { loader: 'path/to/babel-loader', options: { presets: ['@babel/preset-env'] } },
    { loader: 'path/to/eslint-loader' }
  ],
  context: {},
  readResource: fs.readFile.bind(fs)
}, (err, result) => {
  if(err) {
    return console.error(err);
  }
  console.log(result);
});

Other packages similar to loader-runner

webpack

While webpack is a comprehensive module bundler, it internally uses a mechanism similar to loader-runner to process files with loaders. Compared to loader-runner, webpack offers a broader set of features for bundling, optimization, and asset management but is more complex and requires more configuration.

cosmiconfig

Cosmiconfig is designed for loading and parsing configuration files from various formats. It's similar to loader-runner in the sense that both deal with processing files, but cosmiconfig focuses on configuration files and does not directly relate to webpack loaders or the concept of transforming file content.

README

loader-runner

import { runLoaders } from "loader-runner";

runLoaders({
	resource: "/abs/path/to/file.txt?query",
	// String: Absolute path to the resource (optionally including query string)

	loaders: ["/abs/path/to/loader.js?query"],
	// String[]: Absolute paths to the loaders (optionally including query string)
	// {loader, options}[]: Absolute paths to the loaders with options object

	context: { minimize: true },
	// Additional loader context which is used as base context

	processResource: (loaderContext, resourcePath, callback) => { ... },
	// Optional: A function to process the resource
	// Must have signature function(context, path, function(err, buffer))
	// By default readResource is used and the resource is added a fileDependency

	readResource: fs.readFile.bind(fs)
	// Optional: A function to read the resource
	// Only used when 'processResource' is not provided
	// Must have signature function(path, function(err, buffer))
	// By default fs.readFile is used
}, function(err, result) {
	// err: Error?

	// result.result: Buffer | String
	// The result
	// only available when no error occured

	// result.resourceBuffer: Buffer
	// The raw resource as Buffer (useful for SourceMaps)
	// only available when no error occured

	// result.cacheable: Bool
	// Is the result cacheable or do it require reexecution?

	// result.fileDependencies: String[]
	// An array of paths (existing files) on which the result depends on

	// result.missingDependencies: String[]
	// An array of paths (not existing files) on which the result depends on

	// result.contextDependencies: String[]
	// An array of paths (directories) on which the result depends on
})

More documentation following...