UNPKG

3.41 kBMarkdownView Raw
1# append-transform [![Build Status](https://travis-ci.org/istanbuljs/append-transform.svg?branch=master)](https://travis-ci.org/istanbuljs/append-transform) [![Coverage Status](https://coveralls.io/repos/github/istanbuljs/append-transform/badge.svg?branch=master)](https://coveralls.io/github/istanbuljs/append-transform?branch=master)
2
3> Install a transform to `require.extensions` that always runs last, even if additional extensions are added later
4
5The [typical require extension](https://gist.github.com/jamestalmage/df922691475cff66c7e6) looks something like this:
6
7```js
8const myTransform = require('my-transform');
9
10const oldExtension = require.extensions['.js'];
11
12require.extensions['.js'] = (module, filename) => {
13 const oldCompile = module._compile;
14
15 module._compile = (code, filename) => {
16 code = myTransform(code);
17 module._compile = oldCompile;
18 module._compile(code, filename);
19 };
20
21 oldExtension(module, filename);
22};
23```
24
25In **almost** all cases, that is sufficient and is the method that should be used (check out [`pirates`](https://www.npmjs.com/package/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).
26
27*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`](https://www.npmjs.com/package/pirates).
28
29References:
30- [Detailed Breakdown of How Require Extensions Work](https://gist.github.com/jamestalmage/df922691475cff66c7e6)
31- The [test suite](https://github.com/avajs/append-transform/blob/master/test/execution-order.js) provides a good overview of how this library manipulates the order in which transforms are applied.
32
33
34## Install
35
36```
37$ npm install --save append-transform
38```
39
40
41## Usage
42
43```js
44const appendTransform = require('append-transform');
45const myTransform = require('my-transform');
46
47appendTransform((code, filename) => {
48 if (myTransform.shouldTransform(filename)) {
49 code = myTransform.transform(code);
50 }
51
52 return code;
53});
54```
55
56## API
57
58### appendTransform(transformFn, [extension])
59
60#### transformFn
61
62Type: `function(code: string, filename: string)`
63
64A 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`](https://www.npmjs.com/package/node-modules-regexp) to help reliably detect `node_modules` paths and avoid transforming them.
65
66#### extension
67
68Type: `string`<br>
69Default: `'.js'`
70
71The extension for the types of files this transform is capable of handling.
72
73
74## License
75
76MIT © [James Talmage](https://github.com/jamestalmage)