npm package: @guaclive/next-transpile-modules
Description: Next.js plugin to transpile code from node_modules (supports TypeScript)
Author: Pierre de la Martinière
Latest version: 3.3.4

# Next.js + Transpile `node_modules`

![Build Status](https://github.com/martpie/next-transpile-modules/workflows/tests/badge.svg)
![Dependencies](https://img.shields.io/david/martpie/next-transpile-modules)

Transpile untranspiled modules from `node_modules` using the Next.js Babel configuration.
Makes it easy to have local libraries and keep a slick, manageable dev experience.

Supports all extensions supported by Next.js: `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.css`, `.scss` and `.sass`.

## What problems does it solve?

This plugin aims to solve the following challenges:

- code transpilation from local packages (think: a monorepo with a `styleguide` package)
- code transpilation from NPM modules using ES6 imports (e.g `lodash-es`)

What this plugin **does not aim** to solve:

- any-package IE11-compatible maker

## Compatibility table

| Next.js version | Plugin version |
| --------------- | -------------- |
| Next.js 9.2+    | 3.x            |
| Next.js 8 / 9   | 2.x            |
| Next.js 6 / 7   | 1.x            |

## Installation

```
npm install --save next-transpile-modules
```

or

```
yarn add next-transpile-modules
```

## Usage

### Classic:

```js
// next.config.js
const withTM = require('next-transpile-modules')(['somemodule', 'and-another']); // pass the modules you would like to see transpiled

module.exports = withTM();
```

**note:** please declare `withTM` as your last plugin (the "most nested" one).

### Scoped packages

You can include scoped packages or nested ones:

```js
const withTM = require('next-transpile-modules')(['@shared/ui', '@shared/utils']);

// ...
```

```js
const withTM = require('next-transpile-modules')(['styleguide/components']);

// ...
```

### With `next-compose-plugins`:

```js
const withPlugins = require('next-compose-plugins');
const withTM = require('next-transpile-modules')(['some-module', 'and-another']);

module.exports = withPlugins([withTM], {
  // ...
});
```

### CSS/SCSS support

Since `next-transpile-modules@3` and `next@>9.2`, this plugin can also transpile CSS included in your transpiled packages. SCSS/SASS is also supported since `next-transpile-modules@3.1.0`.

In your transpiled package:

```js
// shared-ui/components/Button.js
import styles from './Button.module.css';

function Button(props) {
  return (
    <button type='button' className={styles.error}>
      {props.children}
    </button>
  );
}

export default Button;
```

```css
/* shared-ui/components/Button.module.js */
.error {
  color: white;
  background-color: red;
}
```

In your app:

```js
// next.config.js
const withTM = require('next-transpile-modules')(['shared-ui']);

// ...
```

```jsx
// pages/home.jsx
import React from 'react';
import Button from 'shared-ui/components/Button';

const HomePage = () => {
  return (
    <main>
      {/* will output <button class="Button_error__xxxxx"> */}
      <Button>Styled button</Button>
    </main>
  );
};

export default HomePage;
```

It also supports global CSS import packages located in `node_modules`:

```jsx
// pages/_app.js
import 'shared-ui/styles/global.css'; // will be imported globally

export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}
```

## FAQ

### What is the difference with `@weco/next-plugin-transpile-modules`?

- it is maintained, `@weco`'s seems dead
- it supports TypeScript
- it supports CSS modules (since Next.js 9.2)
- it supports `.mjs`

### I have trouble making it work with Next.js 7

Next.js 7 introduced Webpack 4 and Babel 7, [which changed a couple of things](https://github.com/zeit/next.js/issues/5393#issuecomment-458517433), especially for TypeScript and Flow plugins.

If you have a transpilation error when loading a page, check that your `babel.config.js` is up to date and valid, [you may have forgotten a preset](https://github.com/martpie/next-transpile-modules/issues/1#issuecomment-427749256) there.

### I have trouble with transpilation and Flow/TypeScript

In your Next.js app, make sure you use a `babel.config.js` and not a `.babelrc` as Babel's configuration file (see explanation below).

**Since Next.js 9, you probably don't need that file anymore**, as TypeScript is supported natively.

### I have trouble with transpilation and Yarn workspaces

If you get a transpilation error when using Yarn workspaces, make sure you are using a `babel.config.js` and not a `.babelrc`. The former is [a project-wide Babel configuration](https://babeljs.io/docs/en/config-files), when the latter works for relative paths only (and won't work as Yarn install dependencies in a parent directory).

### I have trouble with transpilation and my custom `.babelrc`

Make sure you are using a `babel.config.js` and not a `.babelrc`. The former is [a project-wide Babel configuration](https://babeljs.io/docs/en/config-files), when the latter works for relative paths only.

### I have trouble with Yarn and hot reloading

If 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.

You 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.

### I have trouble making it work with Lerna

Lerna'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** (<- this, in caps).

This is not coming from me, but [from Lerna's maintainer](https://github.com/lerna/lerna/issues/1243#issuecomment-401396850).

So 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.

### But... I really need to make it work with Lerna!

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.

```js
const withTM = require('next-transpile-modules')(['@your-project/shared', '@your-project/styleguide']);

module.exports = withTM({
  webpack: (config, options) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      // Will make webpack look for these modules in parent directories
      '@your-project/shared': require.resolve('@your-project/shared'),
      '@your-project/styleguide': require.resolve('@your-project/styleguide')
      // ...
    };
    return config;
  }
});
```

### I have trouble with duplicated dependencies or the `Invalid hook call` error in `react`

It 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.

Let's take the following setup: one Next.js app ("Consumer"), and one Styleguide library.

You 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`.

The 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.

You can tell Webpack how to resolve the `react` of your Styleguide to use the version in your Next.js app like that:

```diff
const withTM = require('next-transpile-modules')(['styleguide']);

module.exports = withTM({
  webpack: (config) => {
+   config.resolve.alias['react'] = path.resolve(__dirname, '.', 'node_modules', 'react');

    return config
  },
});
```

Please 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.

It is not a great solution, but it works. Any help to find a more future-proof solution is welcome.