{"id":13423815,"url":"https://github.com/martpie/next-transpile-modules","last_synced_at":"2025-10-07T13:30:24.192Z","repository":{"id":33149537,"uuid":"144122095","full_name":"martpie/next-transpile-modules","owner":"martpie","description":"Next.js plugin to transpile code from node_modules. Please see: https://github.com/martpie/next-transpile-modules/issues/291","archived":false,"fork":true,"pushed_at":"2023-07-24T11:43:57.000Z","size":3025,"stargazers_count":1125,"open_issues_count":4,"forks_count":85,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-05-22T08:43:57.562Z","etag":null,"topics":["modules","nextjs","plugin","transpile"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"wellcometrust/next-plugin-transpile-modules","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martpie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["martpie"]}},"created_at":"2018-08-09T08:17:58.000Z","updated_at":"2024-05-11T00:03:42.000Z","dependencies_parsed_at":"2023-01-16T22:45:27.694Z","dependency_job_id":null,"html_url":"https://github.com/martpie/next-transpile-modules","commit_stats":null,"previous_names":["martpie/next-plugin-transpile-modules"],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martpie%2Fnext-transpile-modules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martpie%2Fnext-transpile-modules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martpie%2Fnext-transpile-modules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martpie%2Fnext-transpile-modules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martpie","download_url":"https://codeload.github.com/martpie/next-transpile-modules/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234141351,"owners_count":18785840,"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":["modules","nextjs","plugin","transpile"],"created_at":"2024-07-31T00:00:43.126Z","updated_at":"2025-10-07T13:30:23.458Z","avatar_url":"https://github.com/martpie.png","language":"JavaScript","funding_links":["https://github.com/sponsors/martpie"],"categories":["Extensions","JavaScript"],"sub_categories":[],"readme":"\u003e **Note**\n\u003e All `next-transpile-modules` features have natively landed to Next.js 13.1, you can check [the migration guide here](https://github.com/martpie/next-transpile-modules/releases/tag/the-end).\n\u003e\n\u003e This package is now officially deprecated and on life-support.\n\u003e\n\u003e PRs with fixes are welcome and I will help review them, but that's it. I **highly** recommend contributing to Next.js in case your setup is not working there.\n\n---\n\n# Next.js + Transpile `node_modules`\n\n![Build Status](https://github.com/martpie/next-transpile-modules/workflows/tests/badge.svg)\n\nTranspile modules from `node_modules` using the Next.js Babel configuration.\n\nMakes it easy to have local libraries and keep a slick, manageable dev experience.\n\n- Supports transpilation of all extensions supported by Next.js: `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.css`, `.scss` and `.sass`\n- Enable hot-reloading on local packages\n- Enable global and local CSS loading from local/npm packages\n- Most setups should work out of the box (npm, yarn, pnpm, ...)\n\n## What problems does it solve?\n\nThis plugin aims to solve the following challenges:\n\n- code transpilation from local packages (think: a monorepo with a `styleguide` package)\n- code transpilation from NPM modules using ES6 imports (e.g `lodash-es`)\n\nWhat this plugin **does not aim** to solve:\n\n- any-package IE11-compatible maker\n\n## Compatibility table\n\n| Next.js version   | Plugin version     |\n| ----------------- | ------------------ |\n| Next.js 13        | 10.x               |\n| Next.js 12        | 9.x                |\n| Next.js 11        | 8.x                |\n| Next.js 9.5+ / 10 | 4.x, 5.x, 6.x, 7.x |\n| Next.js 9.2       | 3.x                |\n| Next.js 8 / 9     | 2.x                |\n| Next.js 6 / 7     | 1.x                |\n\nLatest Next.js version tested: **13.4.12**.\n\n## Installation\n\n```\nnpm install --save next-transpile-modules\n```\n\nor\n\n```\nyarn add next-transpile-modules\n```\n\n## Usage\n\n### withTM(transpileModules [, options])\n\n- `transpileModules` String[]: modules to be transpiled\n- `options` Object (optional)\n  - `resolveSymlinks` Boolean: Enable symlinks resolution to their real path by Webpack (default to `true`)\n  - `debug` Boolean: Display some informative logs in the console (can get noisy!) (default to `false`)\n  - `__unstable_matcher` (path) =\u003e boolean: Custom matcher that will override the default one. Don't use it.\n\n#### Note on `resolveSymlinks`\n\nNode.js resolution is based on the fact that symlinks are resolved. Not resolving them will alter the behavior, but there are some cases where the alternative behavior makes things a lot easier.\n\nIf:\n\n- You are using `npm/yarn link` to link packages into node_modules.\n- You are using `npm` with `file:` dependencies that live outside of your project directory\n  - `npm` will create symlinks in this case. Yarn will copy instead.\n\n**you should set `resolveSymlinks: false`**, which results which will make things work as expected.\n\nFor other scenarios like:\n\n- `pnpm`\n- `yarn/npm` workspaces\n- `yarn 2` portals\n\nyou should keep `resolveSymlinks: true` (default).\n\n#### Examples\n\n```js\n// next.config.js\nconst withTM = require('next-transpile-modules')(['somemodule', 'and-another']); // pass the modules you would like to see transpiled\n\nmodule.exports = withTM({});\n```\n\n**Notes:**\n\n- please declare `withTM` as your last plugin (the outermost one).\n- ~~make sure all your packages have [a valid `main` field](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#main).~~ (not needed anymore since `7.1.0`)\n- there is currently no way to transpile only parts of a package, it's all or nothing\n\n### Scoped packages\n\nYou can include scoped packages or nested ones:\n\n```js\nconst withTM = require('next-transpile-modules')(['@shared/ui', '@shared/utils']);\n\n// ...\n```\n\n```js\nconst withTM = require('next-transpile-modules')(['styleguide/node_modules/lodash-es']);\n\n// ...\n```\n\nIf you need to install all packages of a certain scope (**it is highly discouraged**), you can do the following:\n\n```js\nconst packageJSON = require('./package.json');\nconst transpiledPackages = Object.keys(packageJSON.dependencies).filter((it) =\u003e it.includes('@shared/'));\n\nconst withTM = require('next-transpile-modules')(transpiledPackages);\n```\n\n### With `next-compose-plugins`:\n\n```js\nconst withPlugins = require('next-compose-plugins');\nconst withTM = require('next-transpile-modules')(['some-module', 'and-another']);\n\nmodule.exports = withPlugins([withTM], {\n  // ...\n});\n```\n\n### CSS/SCSS support\n\nSince `next-transpile-modules@3` and `next@\u003e9.2`, this plugin can also transpile CSS included in your transpiled packages. SCSS/SASS is also supported since `next-transpile-modules@3.1.0`.\n\nIn your transpiled package:\n\n```js\n// shared-ui/components/Button.js\nimport styles from './Button.module.css';\n\nfunction Button(props) {\n  return (\n    \u003cbutton type='button' className={styles.error}\u003e\n      {props.children}\n    \u003c/button\u003e\n  );\n}\n\nexport default Button;\n```\n\n```css\n/* shared-ui/components/Button.module.css */\n.error {\n  color: white;\n  background-color: red;\n}\n```\n\nIn your app:\n\n```js\n// next.config.js\nconst withTM = require('next-transpile-modules')(['shared-ui']);\n\n// ...\n```\n\n```jsx\n// pages/home.jsx\nimport React from 'react';\nimport Button from 'shared-ui/components/Button';\n\nconst HomePage = () =\u003e {\n  return (\n    \u003cmain\u003e\n      {/* will output \u003cbutton class=\"Button_error__xxxxx\"\u003e */}\n      \u003cButton\u003eStyled button\u003c/Button\u003e\n    \u003c/main\u003e\n  );\n};\n\nexport default HomePage;\n```\n\nIt also supports global CSS import packages located in `node_modules`:\n\n```jsx\n// pages/_app.js\nimport 'shared-ui/styles/global.css'; // will be imported globally\n\nexport default function MyApp({ Component, pageProps }) {\n  return \u003cComponent {...pageProps} /\u003e;\n}\n```\n\n## Contributing\n\n- clone\n- `cd next-transpile-modules`\n- `yarn`\n\nIf you want to update the Next.js tested version:\n\n- update `scripts/next-update.sh` with the latest Next.js version\n- make sure `npm`, `yarn` and `pnpm` are installed\n- `yarn setup`\n- `bash scripts/next-update.sh`\n\nPush your changes and Github Actions will test everything as it should be.\n\n## FAQ\n\n### What is the difference with `@weco/next-plugin-transpile-modules`?\n\n- it is maintained, `@weco`'s seems dead\n- it supports TypeScript\n- it supports CSS modules (since Next.js 9.2)\n- it supports `.mjs`\n\n### Where can I find a setup that works?\n\n[Here you go](https://github.com/martpie/monorepo-typescript-next-the-sane-way)!\n\n### A new version of Next.js is available/I just setup my project, and my build is breaking because of this plugin\n\nIt is important to understand that this plugin is a big hack of the Next.js Webpack configuration. When the Next.js team pushes an update to their build configuration, the changes `next-transpile-modules` bring may be outdated, and the plugin needs to be updated (which is a breaking change for this plugin, as the updated plugin is usually not retro-compatible with the previous versions of Next.js).\n\nNow, this build problem can happen when you install your dependencies with `npm install`/`yarn install` (in your CI pipeline for example). Those commands **may re-resolve your `next` dependency of your `package.json` to a newer one**, and this newer one may have critical Webpack changes, hence breaking your build.\n\nThe way to fix it is easy, and it is what you should always do: **install your dependencies with `npm ci` (\"clean install\") or `yarn --frozen-lockfile`**. This will force `npm` or `yarn` to use the version of Next.js declared in your lock file, instead of downloading the latest one compatible with the version accepted by your `package.json`.\n\nSo basically: use your lock files right, and understand what problems they are solving ;)\n\nmore:\n\n- check the [compatibility table](#compatibility-table) of this plugin\n- read more about semver and version resolutions: https://docs.npmjs.com/misc/semver\n\n### I have trouble making it work after upgrading to v5/v6\n\nPlease make sure to [read the changelog](https://github.com/martpie/next-transpile-modules/releases).\n\n### I have trouble with transpilation and my custom `.babelrc`\n\nIf you get a transpilation error when using a custom Babel configuration, make sure you are using a `babel.config.js` and not a `.babelrc`.\n\nThe former is [a project-wide Babel configuration](https://babeljs.io/docs/en/config-files), when the latter works for relative paths only (and may not work for Yarn for example, as it installs dependencies in a parent directory).\n\n### I have trouble with Yarn and hot reloading\n\nIf you add a local library (let's say with `yarn add ../some-shared-module`), Yarn will copy those files by default, instead of symlinking them. So your changes to the initial folder won't be copied to your Next.js `node_modules` directory.\n\nYou can go back to `npm`, or use Yarn workspaces. See [an example](https://github.com/zeit/next.js/tree/canary/examples/with-yarn-workspaces) in the official Next.js repo.\n\n### How do I find out which package is causing a runtime exception?\n\n- add `config.optimization.minimize = false;` to you `next.config.js`'s Webpack configuration\n- run a production build\n- run it on the browser throwing the error\n- open the console, jump to the line where it failed\n- goes a little bit up in the lines of code, and check the Webpack comments telling you which module is affected\n\n### I have trouble making it work with Lerna\n\nLerna's purpose is to publish different packages from a monorepo, **it does not help for and does not intend to help local development with local modules** (\u003c- this, **IN CAPS**).\n\nThis is not coming from me, but [from Lerna's maintainer](https://github.com/lerna/lerna/issues/1243#issuecomment-401396850).\n\nSo you are probably [using it wrong](https://github.com/martpie/next-transpile-modules/issues/5#issuecomment-441501107), and I advice you to use `npm` or Yarn workspaces instead.\n\n### But... I really need to make it work with Lerna!\n\nAgain, most probably a bad idea. You may need to tell your Webpack configuration how to properly resolve your scoped packages, as they won't be installed in your Next.js directory, but the root of your Lerna setup.\n\n```js\nconst withTM = require('next-transpile-modules')(['@your-project/shared', '@your-project/styleguide']);\n\nmodule.exports = withTM({\n  webpack: (config, options) =\u003e {\n    config.resolve.alias = {\n      ...config.resolve.alias,\n      // Will make webpack look for these modules in parent directories\n      '@your-project/shared': require.resolve('@your-project/shared'),\n      '@your-project/styleguide': require.resolve('@your-project/styleguide'),\n      // ...\n    };\n    return config;\n  },\n});\n```\n\n### I have trouble with duplicated dependencies or the `Invalid hook call` error in `react`\n\nIt can happen that when using `next-transpile-modules` with a local package and `npm`, you end up with duplicated dependencies in your final Next.js build. It is important to understand _why_ it happens.\n\nLet's take the following setup: one Next.js app (\"Consumer\"), and one Styleguide library.\n\nYou will probably have `react` as a `peerDependencies` and as a `devDependecy` of the Styleguide. If you use `npm i`, it will create a symlink to your Styleguide package in your \"Consumer\" `node_modules`.\n\nThe thing is in this shared package, you also have a `node_modules`. So when your shared modules requires, let's say `react`, Webpack will resolve it to the version in your Styleguide's `node_modules`, and not your Consumer's `node_modules`. Hence the duplicated `react` in your final bundles.\n\nYou can tell Webpack how to resolve the `react` of your Styleguide to use the version in your Next.js app like that:\n\n```diff\nconst withTM = require('next-transpile-modules')(['styleguide']);\n\nmodule.exports = withTM({\n  webpack: (config, options) =\u003e {\n+   if (options.isServer) {\n+     config.externals = ['react', ...config.externals];\n+   }\n+\n+   config.resolve.alias['react'] = path.resolve(__dirname, '.', 'node_modules', 'react');\n\n    return config\n  },\n});\n```\n\nPlease note, the above [will only work](https://github.com/zeit/next.js/issues/9022#issuecomment-610255555) if `react` is properly declared as `peerDependencies` or `devDependencies` in your referenced package.\n\nIt is not a great solution, but it works. Any help to find a more future-proof solution is welcome.\n\n## Credits\n\nAll the honor goes to [James Gorrie](https://github.com/jamesgorrie) who created the first version of this plugin.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartpie%2Fnext-transpile-modules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartpie%2Fnext-transpile-modules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartpie%2Fnext-transpile-modules/lists"}