transpile-webpack-plugin/README.md

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
  <h1>Transpile Webpack Plugin</h1>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![download][download]][npm-url]
[![license][license]][license-url]
[![size][size]][size-url]
[![cicd][cicd]][cicd-url]

# Transpile Webpack Plugin

The webpack plugin that transpiles input files into output files individually without bundling together.

Input files are collected from files directly or indirectly imported by the [entry](https://webpack.js.org/configuration/entry-context/#entry), then get compiled and ouputted keeping the same directory structure in the output directory.

Transpiling with webpack is especially helpful when both user interface logics and source file path related logics are involved, such as building SSR(server side rendering) in a heavyweight NodeJS server. Please make best of it.

Note that this plugin replies on features of webpack v5. The latest webpack is supposed to be used when possible.

## Getting Started

To begin, you'll need to install `transpile-webpack-plugin`:

```sh
npm i -D transpile-webpack-plugin
```

Or, with any package manager you prefer.

Then, add the plugin to your webpack config. For example:

```js
const TranspilePlugin = require('transpile-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    path: __dirname + '/dist',
  },
  plugins: [new TranspilePlugin(/* options */)],
};
```

Assuming the entry `src/index.js` imports another file `src/constants/greeting.js`, input files will be `src/index.js` `src/constants/greeting.js`. After compilation, output files will be `dist/index.js` `dist/constants/greeting.js`. The common dir of input files is used as the base dir to evaluate the relative paths of output files in output dir.

Just a reminder, if to run output files with NodeJS, don't forget to set the [target](https://webpack.js.org/configuration/target/) as `node` or a node-compatible value so that no breaking code is generated by webpack unexpectedly.

## Blogs

- [Transpile Webpack Plugin: transpiling files with webpack without bundling](https://medium.com/@licg9999/introducing-transpile-webpack-plugin-b8c86c7b0a21)
- [Transpile Webpack Plugin: 让 Webpack 按照源文件的目录结构输出](https://segmentfault.com/a/1190000043177608)

## Options

- **[exclude](#exclude)**
- **[hoistNodeModules](#hoistnodemodules)**
- **[longestCommonDir](#longestcommondir)**
- **[extentionMapping](#extentionmapping)**
- **[preferResolveByDependencyAsCjs](#preferresolvebydependencyascjs)**

### `exclude`

Type: `{string|RegExp|((p: string) => boolean)|string[]|RegExp[]|((p: string) => boolean)[]}`

Default: `[]`

Option `exclude` indicates files to be excluded. Import statements to the excluded in input files are properly adjusted in output files and kept workable. It's similar to the [externals](https://webpack.js.org/configuration/externals/) except that the import path auto adjustment. It'll be useful when you copy some third-party files and want to use them as they are.

By the way, excluding `node_modules` with this option is a bit trivial because some helpers of webpack loaders also living there are not runnable before compiled. If you need to exclude dependencies in `node_modules`, using [webpack-node-externals](https://github.com/liady/webpack-node-externals) might be a better choice.

With this option as string, input files whose aboslute paths begin with it will be excluded. With this option as regular expression, input files whose absolute paths match it will be excluded. With this option as function, input files whose absolute paths are passed into the call of it and end up with `true` will be excluded.

### `hoistNodeModules`

Type: `{boolean}`

Default: `true`

Option `hoistNodeModules` indicates whether to evaluate output paths for input files from or not from `node_modules` separately, and keep input files from `node_modules` outputted into `node_modules` just under output dir. It's usable to flatten the output directory structure a little bit.

Given input files `src/index.js` `node_modules/lodash/lodash.js` and output dir `dist`, with this option `true`, output files will be `dist/index.js` `dist/node_modules/lodash/lodash.js`. But with this option `false`, output files will be `dist/src/index.js` `dist/node_modules/lodash/lodash.js`.

### `longestCommonDir`

Type: `{string|undefined}`

Default: `undefined`

Option `longestCommonDir` indicates the limit of the common dir to evaluate relative paths of output files in output dir. When this option is shorter than the common dir of input files, this option is used against input files to evaluate relative paths of output files in output dir. Otherwise, the common dir of input files is used.

Given input files `src/server/index.js` `src/server/constants/greeting.js` and output dir `dist`, with this option `undefined`, output files will be `dist/index.js` `dist/constants/greeting.js`. But with this option `'./src'`, output files will be `dist/server/index.js` `dist/server/constants/greeting.js`.

Though, given input files `src/index.js` `src/server/constants/greeting.js` and output dir `dist`, with this option `'./src/server'`, output files will still be `dist/index.js` `dist/server/constants/greeting.js` because the common dir of input files is shorter than this option.

### `extentionMapping`

Type: `{Record<string, string>}`

Default: `{}`

Option `extentionMapping` indicates how file extensions are mapped from input to output. By default, one output file will have exactly the same file extension as the input file. But you may change it by this option. With this option `{ '.ts': '.js' }`, any input file with ext `.ts` will have the output file with ext `.js`.

### `preferResolveByDependencyAsCjs`

Type: `boolean`

Default: `true`

Options `preferResolveByDependencyAsCjs` indicates whether to try to resolve dependencies by CommonJS [exports](https://nodejs.org/api/packages.html#conditional-exports) regardless of types of import statements. It's useful when the target is `node` because `.mjs` files are treated as ES modules in NodeJS and [can't be required](https://nodejs.org/api/esm.html#require) by webpack generated CommonJS files.

Given `{ "exports": { "import": "index.mjs", "require": "index.cjs" } }` in `package.json` of a dependency, with this option `true`, either `import` or `require` to this dependency will end up with `index.cjs`. And with this option `false`, `import` is with `index.mjs` and `require` is with `index.cjs`(, which is also the default behavior of webpack).

## Known limits

**<a name="known-limit-01" href="#known-limit-01">01:</a> Can't handle circular dependencies in the same way as NodeJS.**

In NodeJS, top-level logics in a file run exactly at the time when it's required, which makes circular dependencies possible to work. Take an example of files `a.js` and `b.js`:

```js
// In file 'a.js'
const b = require('./b');

function main() {
  b.goo();
}

function foo() {
  console.log('lorem ipsum');
}

module.exports = { foo };

main();

// In file 'b.js'

const a = require('./a');

function goo() {
  a.foo();
}

module.exports = { goo };
```

When `a.js` runs, an error of `TypeError: a.foo is not a function` thrown from `b.js`. But putting the line `const b = require('./b');` just after `module.exports = { foo };` resolves the problem:

```diff
// In file 'a.js'
-
-const b = require('./b');

function main() {
  b.goo();
}

function foo() {
  console.log('lorem ipsum');
}

module.exports = { foo };
+
+const b = require('./b');

main();
```

Though, for a webpack generated file, the real exporting is always done in the end of it. Webpack collects all the exports into an internal variable `__webpack_exports__`, then exports it at last, which makes circular dependencies always break.

Making circular dependencies is a bad practice. But you might have to face them if using some libs that are popular but maintained since the early releases of NodeJS, like [jsdom](https://github.com/jsdom/jsdom). When this happens, please use the [externals](https://webpack.js.org/configuration/externals/) to leave the libs untouched.

**<a name="known-limit-02" href="#known-limit-02">02:</a> Can't conditionally import not-yet-installed dependencies.**

Webpack always detects and resolves import statements regardless of whether they run conditionally. Logics as below end up with the conditionally imported dependency `colorette` resolved:

```js
function print(message, color) {
  if (typeof color === 'string') {
    message = require('colorette')[color](message);
  }
  console.log(message);
}
```

Besides, conditionally importing any not-yet-installed dependency causes the compile-time error of `Module not found` in webpack. As a result, either, you need to make sure the conditionally imported dependency installed. Or, use the [externals](https://webpack.js.org/configuration/externals/) to leave it untouched.

**<a name="known-limit-03" href="#known-limit-03">03:</a> Can't import `.node` files directly.**

By default, importing `.node` files causes the compile-time error of `Module parse failed` in webpack. Using [node-loader](http://github.com/webpack-contrib/node-loader) along with the plugin option [extentionMapping](#extentionmapping) as `{ '.node': '.js' }` might resolve some very basic cases but the node-loader itself doesn't handle paths well so it's not recommeneded. Instead, you may use the [externals](https://webpack.js.org/configuration/externals/) to leave the JS files that use the `.node` files untouched.

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.
[CONTRIBUTING][contributing-url]

## License

[MIT][license-url]

[npm]: https://img.shields.io/npm/v/transpile-webpack-plugin.svg
[npm-url]: https://npmjs.com/package/transpile-webpack-plugin
[node-url]: https://nodejs.org/
[node]: https://img.shields.io/node/v/transpile-webpack-plugin.svg
[download]: https://img.shields.io/npm/dw/transpile-webpack-plugin
[license]: https://img.shields.io/github/license/licg9999/transpile-webpack-plugin
[license-url]: https://github.com/licg9999/transpile-webpack-plugin/blob/master/LICENSE
[size]: https://packagephobia.com/badge?p=transpile-webpack-plugin
[size-url]: https://packagephobia.com/result?p=transpile-webpack-plugin
[cicd]: https://github.com/licg9999/transpile-webpack-plugin/actions/workflows/verify-and-release.yml/badge.svg
[cicd-url]: https://github.com/licg9999/transpile-webpack-plugin/actions/workflows/verify-and-release.yml
[contributing-url]: https://github.com/licg9999/transpile-webpack-plugin/blob/master/CONTRIBUTING.md