next-transpile-modules

next-transpile-modules is a Next.js configuration plugin that forces specified node_modules packages (local monorepo packages or npm-published ES module packages) through Next.js’s own Babel and webpack pipeline. Before Next.js natively supported this, importing an untranspiled local package or a modern ESM-only npm package into a Next.js app would fail at build time or ship unusable syntax to the browser — this plugin patches the webpack config to include the named packages in the transpilation step.

It supports transpiling JS, JSX, TS, TSX, MJS, CSS, SCSS, and Sass from the named modules, enables hot-reloading for local monorepo packages, and works across npm, Yarn, and pnpm setups. As of Next.js 13.1, all its core functionality (transpilePackages in next.config.js) landed natively in the framework, and the maintainer has marked this package deprecated and in “life-support” mode — still accepting community PRs but no longer under active feature development.

What You Get

• A withTM(modules, options) wrapper for next.config.js that adds named packages to Next’s transpilation step
• Support for JS, JSX, TS, TSX, MJS, CSS, SCSS, and Sass files inside transpiled packages
• Hot-reloading support for local monorepo packages during development
• CSS Modules and global CSS import support from transpiled packages (since v3+)
• A resolveSymlinks option to handle npm-link/file-dependency setups differently from Yarn/pnpm workspaces

Common Use Cases

• Sharing a local styleguide/ui package across a monorepo’s Next.js app with hot-reloading in development
• Consuming an ESM-only npm package (like lodash-es) that ships syntax Next’s default build doesn’t transpile
• Importing CSS or SCSS directly from a shared local or npm package into Next.js pages

Under The Hood

Architecture The entire plugin lives in a single src/next-transpile-modules.js file (~285 lines) that returns a higher-order Next.js config function: it resolves the real filesystem paths of the named modules (accounting for symlinks via resolveSymlinks), builds a matcher function that tests whether a given module path belongs to the transpile list, and rewrites the webpack config’s module.rules so those paths are routed through Next’s built-in Babel loader (and CSS/Sass loaders) instead of being treated as pre-built node_modules code. Tech Stack Plain JavaScript targeting the Next.js webpack config API directly (config.module.rules, config.resolve), with no external runtime dependencies beyond Node’s path/fs; tests run through Jest plus jest-puppeteer for browser-level verification of the plugin against real Next.js example apps. Code Quality The src/__tests__ directory and root-level example apps (per the compatibility table spanning Next.js 6 through 13) show the plugin was verified against many Next.js versions via a scripts/next-update.sh process, reflecting the maintenance burden the README itself describes as “a big hack of the Next.js webpack configuration” that breaks whenever Next.js changes its internal build config — the README candidly documents this fragility and recommends lockfile discipline (npm ci/yarn --frozen-lockfile) to avoid surprise breakage. API Design The single-function withTM(['pkg-a', 'pkg-b']) API is minimal and composes with other Next.js plugin wrappers (documented alongside next-compose-plugins), but the README’s extensive FAQ section (covering Lerna, Yarn symlink behavior, duplicate React instances) signals that real-world usage often requires additional webpack alias configuration beyond the plugin’s defaults.