Next.js monorepo "Module parse failed" needing transpilePackages in CI

By Daniel Zoghalchali·Latchkey

Next.js does not transpile dependencies in node_modules by default. In a monorepo, an internal workspace package shipped as raw TypeScript or JSX fails to parse during next build unless you list it in transpilePackages.

What this error means

next build fails with "Module parse failed: Unexpected token" or "You may need an appropriate loader" pointing at a file inside a sibling workspace package such as packages/ui.

Module parse failed: Unexpected token (5:7)
You may need an appropriate loader to handle this file type.
| export function Button({ label }: { label: string }) {
> ...
  ./node_modules/@acme/ui/src/Button.tsx

Common causes

A workspace package ships untranspiled source

The internal package exports TypeScript or JSX directly, which Next does not compile because it lives under node_modules.

The package is not listed in transpilePackages

Without an explicit opt-in, Next skips transpiling the dependency and webpack cannot parse the syntax.

How to fix it

Add the package to transpilePackages

1. Identify the internal package from the failing module path.
2. Add its package name to transpilePackages in next.config.
3. Re-run next build so Next compiles it.

// next.config.js
module.exports = { transpilePackages: ['@acme/ui'] }

Or build the package to JS before consuming it

Alternatively, compile the workspace package to plain JS and point its main/exports at the built output so no transpilation is needed.

How to prevent it

• List untranspiled internal packages in transpilePackages.
• Or publish/build workspace packages to plain JS before use.
• Keep the list in sync as you add internal packages.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation