pnpm dev --webpack — Why a Content Layer Forces You to Ditch Turbopack
A freshly scaffolded Next.js starter that refuses to start — and the build flag that's invisible unless you already know you need it.
A fresh Next.js project, scaffolded from a starter, with Contentlayer2 as the content layer. Running pnpm dev produces an error, a crash, or a blank page — depending on the version. Running pnpm dev --webpack works perfectly.
The difference is the bundler. Next.js 15+ ships Turbopack as the default development bundler. Contentlayer2 is incompatible with Turbopack. The fix is a single flag — but you would not know to use it unless someone told you or you read the error output very carefully, because the failure mode does not say "Turbopack is the problem."
The PHP reflex
In PHP, the concept of a "bundler" does not exist in the same way. When you run symfony server:start or php artisan serve, the server starts and serves your application. The template engine (Twig, Blade) is a library loaded by your framework, not a separate build step with its own compatibility matrix.
In Next.js, a significant portion of development tooling is concerned with bundling — taking your TypeScript, JSX, CSS, and static assets and producing the files the browser receives. Two bundlers exist: webpack (older, stable, compatible with everything) and Turbopack (newer, faster for many projects, but incompatible with some libraries).
A PHP developer encountering this for the first time might spend time debugging the content format, the MDX syntax, or the configuration file — all of which are fine. The problem is at the bundler level, a layer that has no analogue in the PHP development model.
Why this matters before the first deploy
The --webpack flag is only needed in development. At build time (pnpm build), Next.js uses webpack regardless of the dev setting. So the application builds and deploys correctly — but local development fails, creating a mismatch where CI passes and the developer's machine does not.
This is the kind of mismatch that erodes trust in the local environment. A PHP developer who has never had a toolchain that compiles frontend assets may interpret the failure as a misconfiguration of their own machine, spending time on Docker, Node versions, or system dependencies before discovering it was a build tool flag.
Delaa