{"id":16969934,"url":"https://github.com/licg9999/transpile-webpack-plugin","last_synced_at":"2025-03-22T14:31:19.021Z","repository":{"id":64913742,"uuid":"547289674","full_name":"licg9999/transpile-webpack-plugin","owner":"licg9999","description":"Transpiles input files into output files individually without bundling together","archived":false,"fork":false,"pushed_at":"2023-05-17T14:35:28.000Z","size":107,"stargazers_count":15,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T12:02:08.150Z","etag":null,"topics":["javascript","nodejs","transpile","transpile-webpack-plugin","webpack","webpack-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/licg9999.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support-helpers/constants.ts","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-07T12:46:31.000Z","updated_at":"2025-01-13T00:18:58.000Z","dependencies_parsed_at":"2024-06-19T02:42:14.311Z","dependency_job_id":"00f1da99-f4f4-4e61-8a3e-39945a735e0d","html_url":"https://github.com/licg9999/transpile-webpack-plugin","commit_stats":{"total_commits":36,"total_committers":1,"mean_commits":36.0,"dds":0.0,"last_synced_commit":"19066870923e2ce4b4a0252e7f598e24efd001f4"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licg9999%2Ftranspile-webpack-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licg9999%2Ftranspile-webpack-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licg9999%2Ftranspile-webpack-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licg9999%2Ftranspile-webpack-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/licg9999","download_url":"https://codeload.github.com/licg9999/transpile-webpack-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244971917,"owners_count":20540887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","nodejs","transpile","transpile-webpack-plugin","webpack","webpack-plugin"],"created_at":"2024-10-14T00:26:56.593Z","updated_at":"2025-03-22T14:31:18.731Z","avatar_url":"https://github.com/licg9999.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/webpack/webpack\"\u003e\n    \u003cimg width=\"200\" height=\"200\" src=\"https://webpack.js.org/assets/icon-square-big.svg\"\u003e\n  \u003c/a\u003e\n  \u003ch1\u003eTranspile Webpack Plugin\u003c/h1\u003e\n\u003c/div\u003e\n\n[![npm][npm]][npm-url]\n[![node][node]][node-url]\n[![download][download]][npm-url]\n[![license][license]][license-url]\n[![size][size]][size-url]\n[![cicd][cicd]][cicd-url]\n\n# Transpile Webpack Plugin\n\nThe webpack plugin that transpiles input files into output files individually without bundling together.\n\nInput 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.\n\nTranspiling with webpack is especially helpful when source file path based logics are involved, such as registering events in AWS Lambda, or migrations managing with Sequelize CLI.\n\nNotice that this plugin replies on features of webpack v5. The latest webpack is supposed to be used when possible.\n\n## Getting Started\n\nTo begin, you'll need to install `transpile-webpack-plugin`:\n\n```sh\nnpm i -D transpile-webpack-plugin\n```\n\nOr, any other package manager you prefer, like `yarn` or `pnpm`, would work, too.\n\nThen, add the plugin to your webpack config. For example:\n\n```js\nconst TranspilePlugin = require('transpile-webpack-plugin');\n\nmodule.exports = {\n  entry: './src/index.js',\n  output: {\n    path: __dirname + '/dist',\n  },\n  plugins: [new TranspilePlugin(/* options */)],\n};\n```\n\nNow, assuming in the dir `src`, the entry file `src/index.js` imports another file `src/constants/greeting.js`:\n\n```sh\nsrc\n├── constants\n│   └── greeting.js\n└── index.js\n```\n\nWith the webpack config above, after compilation, output files will be:\n\n```sh\ndist\n├── constants\n│   └── greeting.js\n└── index.js\n```\n\nFiles `src/index.js` and `src/constants/greeting.js` are collected as input files. Then, the common dir of input files is used as the base dir to evaluate the relative paths of output files in the output dir `dist`, which results in output files `dist/index.js` and `dist/constants/greeting.js`.\n\nJust 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.\n\n## Blogs\n\n- [Server-side rendering for any React app on any FaaS provider - elaborating by a demo app of SSR with CRA on Netlify](https://github.com/licg9999/server-side-rendering-with-cra-on-netlify)\n- [Transpile Webpack Plugin: transpiling files with webpack without bundling](https://medium.com/@licg9999/introducing-transpile-webpack-plugin-b8c86c7b0a21) ([中文版本](https://segmentfault.com/a/1190000043177608))\n\n## Options\n\n- **[exclude](#exclude)**\n- **[hoistNodeModules](#hoistnodemodules)**\n- **[longestCommonDir](#longestcommondir)**\n- **[extentionMapping](#extentionmapping)**\n- **[preferResolveByDependencyAsCjs](#preferresolvebydependencyascjs)**\n\n### `exclude`\n\nType: `{string|RegExp|((p: string) =\u003e boolean)|string[]|RegExp[]|((p: string) =\u003e boolean)[]}`\n\nDefault: `[]`\n\nOption `exclude` indicates files to be excluded. It's similar to the [externals](https://webpack.js.org/configuration/externals/) except that the import paths to the excluded are properly adjusted automatically. It's useful when you copy some third-party files and want to use them as they are.\n\nThough, excluding `node_modules` with this option is not a good idea. Some helpers of webpack loaders have to be compiled before they become runnable. 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 because it doesn't exclude helpers of webpack loaders.\n\nWith this option as a string (or strings), input files whose aboslute paths begin with it will be excluded. With this option as a regular expression (or regular expression), input files whose absolute paths match it will be excluded. With this option as a function (or functions), input files whose absolute paths are passed into the call of it and end up with `true` will be excluded.\n\n### `hoistNodeModules`\n\nType: `{boolean}`\n\nDefault: `true`\n\nOption `hoistNodeModules` indicates whether to evaluate output paths for input files inside or outside `node_modules` separately, then keep input files from `node_modules` outputted into `node_modules` just under the output dir. It's usable to flatten the output directory structure a little bit.\n\nGiven input files `src/index.js`, `node_modules/lodash/lodash.js` and the output dir `dist`, with this option `true`, output files will be `dist/index.js` and `dist/node_modules/lodash/lodash.js`. But with this option `false`, output files will be `dist/src/index.js` and `dist/node_modules/lodash/lodash.js`.\n\n### `longestCommonDir`\n\nType: `{string|undefined}`\n\nDefault: `undefined`\n\nOption `longestCommonDir` indicates the limit of the common dir to evaluate relative paths of output files in the output dir. When the dir that this option represents is the parent dir of the common dir of input files, this option is used against input files to evaluate relative paths of output files in the output dir. Otherwise, the common dir of input files is used.\n\nGiven input files `src/server/index.js`, `src/server/constants/greeting.js` and the 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`.\n\nThough, given input files `src/index.js`, `src/server/constants/greeting.js` and the output dir `dist`, with this option `'./src/server'`, output files will still be `dist/index.js` `dist/server/constants/greeting.js` because the dir that this options represents is not the parent dir of the common dir of input files.\n\n### `extentionMapping`\n\nType: `{Record\u003cstring, string\u003e}`\n\nDefault: `{}`\n\nOption `extentionMapping` indicates how file extensions are mapped from the input to the output. By default, an output file will have exactly the same file extension as its input file. But you may change the behavior by this option. With this option `{ '.ts': '.js' }`, any input file with ext `.ts` will have the output file with ext `.js`.\n\n### `preferResolveByDependencyAsCjs`\n\nType: `boolean`\n\nDefault: `true`\n\nOptions `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.\n\nGiven `{ \"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` imported. While, with this option `false`, `import` ends up with `index.mjs` imported and `require` ends up with `index.cjs` imported (, which is the default behavior of webpack).\n\n## Known limits\n\n**\u003ca name=\"known-limit-01\" href=\"#known-limit-01\"\u003e01:\u003c/a\u003e Can't handle circular dependencies in the same way as NodeJS.**\n\nIn NodeJS, top-level logics in a file run exactly at the time when it's imported, which makes circular dependencies possible to work. Take an example of files `a.js` and `b.js`:\n\n```js\n// In file 'a.js'\nconst b = require('./b');\n\nfunction main() {\n  b.goo();\n}\n\nfunction foo() {\n  console.log('lorem ipsum');\n}\n\nmodule.exports = { foo };\n\nmain();\n\n// In file 'b.js'\n\nconst a = require('./a');\n\nfunction goo() {\n  a.foo();\n}\n\nmodule.exports = { goo };\n```\n\nWhen `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:\n\n```diff\n// In file 'a.js'\n-\n-const b = require('./b');\n\nfunction main() {\n  b.goo();\n}\n\nfunction foo() {\n  console.log('lorem ipsum');\n}\n\nmodule.exports = { foo };\n+\n+const b = require('./b');\n\nmain();\n```\n\nThough, 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.\n\nMaking 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.\n\n**\u003ca name=\"known-limit-02\" href=\"#known-limit-02\"\u003e02:\u003c/a\u003e Can't conditionally import not-yet-installed dependencies.**\n\nWebpack always detects and resolves import statements regardless of whether they run conditionally. Logics as below end up with the conditionally imported dependency `colorette` resolved:\n\n```js\nfunction print(message, color) {\n  if (typeof color === 'string') {\n    message = require('colorette')[color](message);\n  }\n  console.log(message);\n}\n```\n\nAs a result, conditionally importing any not-yet-installed dependency causes the compile-time error of `Module not found` in webpack. So, 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.\n\n**\u003ca name=\"known-limit-03\" href=\"#known-limit-03\"\u003e03:\u003c/a\u003e Can't import `.node` files directly.**\n\nBy 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' }` resolves some very basic cases. But as the node-loader itself doesn't handle paths well, the practice is 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.\n\n## Contributing\n\nPlease take a moment to read our contributing guidelines if you haven't yet done so.\n[CONTRIBUTING][contributing-url]\n\n## License\n\n[MIT][license-url]\n\n[npm]: https://img.shields.io/npm/v/transpile-webpack-plugin.svg\n[npm-url]: https://npmjs.com/package/transpile-webpack-plugin\n[node-url]: https://nodejs.org/\n[node]: https://img.shields.io/node/v/transpile-webpack-plugin.svg\n[download]: https://img.shields.io/npm/dw/transpile-webpack-plugin\n[license]: https://img.shields.io/github/license/licg9999/transpile-webpack-plugin\n[license-url]: https://github.com/licg9999/transpile-webpack-plugin/blob/master/LICENSE\n[size]: https://packagephobia.com/badge?p=transpile-webpack-plugin\n[size-url]: https://packagephobia.com/result?p=transpile-webpack-plugin\n[cicd]: https://github.com/licg9999/transpile-webpack-plugin/actions/workflows/verify-and-release.yml/badge.svg\n[cicd-url]: https://github.com/licg9999/transpile-webpack-plugin/actions/workflows/verify-and-release.yml\n[contributing-url]: https://github.com/licg9999/transpile-webpack-plugin/blob/master/CONTRIBUTING.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flicg9999%2Ftranspile-webpack-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flicg9999%2Ftranspile-webpack-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flicg9999%2Ftranspile-webpack-plugin/lists"}