Skip to content

istanbuljs/append-transform

Repository files navigation

append-transform Build Status Coverage Status

Install a transform to require.extensions that always runs last, even if additional extensions are added later

The typical require extension looks something like this:

const myTransform = require('my-transform');

const oldExtension = require.extensions['.js'];

require.extensions['.js'] = (module, filename) => {
	const oldCompile = module._compile;

	module._compile = (code, filename) => {
		code = myTransform(code);
		module._compile = oldCompile;
		module._compile(code, filename);
	};

	oldExtension(module, filename);
};

In almost all cases, that is sufficient and is the method that should be used (check out pirates for an easy way to do it correctly). In rare cases you must ensure your transform remains the last one, even if other transforms are added later. For example, nyc uses this module to ensure its transform is applied last so it can capture the final source-map information, and ensure any language extensions it can't understand are already transpiled (ES2015 via babel for instance).

WARNING: You should be sure you actually need this, as it takes control away from the user. Your transform remains the last one applied, even as users continue to add more transforms. This is potentially confusing. Coverage libraries like nyc (and istanbul on which it relies) have valid reasons for doing this, but you should prefer conventional transform installation via pirates.

References:

Install

$ npm install --save append-transform

Usage

const appendTransform = require('append-transform');
const myTransform = require('my-transform');

appendTransform((code, filename) => {
	if (myTransform.shouldTransform(filename)) {
		code = myTransform.transform(code);
	}

	return code;
});

API

appendTransform(transformFn, [extension])

transformFn

Type: function(code: string, filename: string)

A callback that modifies the incoming code argument in some way, and returns the transformed result. filename is provided to filter which files the transform applies to. If a transform should not manipulate a particular file, just return code without modifying it. It is fairly common to avoid transforming files in node_modules. In that case you may want to use node-modules-regexp to help reliably detect node_modules paths and avoid transforming them.

extension

Type: string
Default: '.js'

The extension for the types of files this transform is capable of handling.

License

MIT © James Talmage