# ADR 006: Turbopack

- HTML version: https://robbiepalmer.me/projects/personal-site/adrs/006-turbopack
- Project: Personal Site (https://robbiepalmer.me/projects/personal-site.md)
- Status: Accepted
- Date: 2025-10-18

# Context

I need a bundler and development server for the Next.js application.
The standard default for Next.js has long been **Webpack**.
However, as the application grows, Webpack's build times and HMR (Hot Module Replacement) latency can increase linearly, slowing down the feedback loop.

Requirements:

* **Velocity**: Instant startup and HMR are critical for maintaining flow.
* **Compatibility**: Must work seamlessly with Next.js App Router and server components.

*Alternatives considered:*

* **Webpack**: The stable default. It is "boring" and reliable but significantly slower.
* **Vite**: Ultra-fast, but incompatible with the Next.js App Router dev server (which requires deep integration for React Server Components). Next.js cannot simply "run on Vite".

# Decision

I decided to use **[Turbopack](https://turbo.build/pack)** (via `next dev --turbopack`).

Turbopack is Vercel's Rust-based successor to Webpack. It is designed specifically to handle the complexity of React Server Components with extreme performance.

# Consequences

### Pros

* **Performance**: Written in Rust, it is orders of magnitude faster than Webpack for startup and HMR—tighter [Short Feedback Loops](/projects?tab=philosophy#short-feedback-loops).
* **Lazy Bundling**: It only compiles the pages/components currently requested, meaning a large project starts as fast as a small one.
* **Easy Revert**: It is purely an opt-in flag. If issues arise, I can simply remove `--turbopack` and fall back to Webpack immediately.
* **Future Proof**: It is the designated future of the Next.js compiler infrastructure.

### Cons

* **Stability**: While stable for development in recent Next.js versions, it may still have edge-case bugs compared to the decade-old Webpack.
* **Plugin Ecosystem**: It does not support the full range of Webpack loaders/plugins (though most modern Next.js apps don't need custom Webpack config).

---

Markdown index of this site: https://robbiepalmer.me/llms.txt