A Next.js Parse Error That Was One Config Option Away

TL;DR

• The admin app failed on load parsing an index.ts from a shared library — ES module vs CommonJS export syntax.
• yarn type check passed, which ruled out the TypeScript config and pointed at bundling instead.
• The fix was adding the shared library to transpilePackages in next.config.js.
• Verified through a real staging deploy and app tests on both Android and iOS.

My admin app wouldn’t load. The error was an unexpected token at the very start of an index.ts file belonging to a shared library — the classic shape of a module versus CommonJS disagreement over export syntax.

Narrowing it down

Two candidates: the shared library’s TypeScript configuration, or the admin app’s Next.js configuration.

Running yarn type check failed to reproduce the error. That’s the useful result — TypeScript is perfectly happy with the file, so the syntax is valid and the problem is in how the code gets bundled, not how it’s typed. That eliminated half the search space in one command.

The answer was in the docs

Reading the Next.js documentation, transpilePackages is exactly for this: packages that ship untranspiled source which Next.js needs to compile itself rather than consume as-is.

Adding our shared library to that list in next.config.js and reloading the dev environment made the error disappear entirely.

Always check the docs. I’d been reasoning about webpack internals when the framework had a documented option for precisely this situation.

Verifying properly

A dev server going quiet isn’t proof, so I deployed to staging using AWS credentials to exercise the real production build path. That worked cleanly. Then I ran app functionality tests on both Android and iOS, including data resets and user interactions, to confirm nothing downstream had shifted.

The underlying lesson is about dependency compilation boundaries. In a monorepo, a shared library sits in an awkward position — it’s not a published package with a build step, but it’s not local source either. transpilePackages is how you tell the bundler which side of that line to treat it as.