Turbopack Complete Guide | Next.js Ultra-Fast Bundler

· 20분 읽기 · 수정 intermediate tutorial
Turbopack Complete Guide | Next.js Ultra-Fast Bundler

이 글의 핵심

Turbopack is Vercel's Rust-based successor to Webpack. Built for Next.js, it delivers 10x faster updates through incremental computation and native speed.

Introduction

Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust. Created by Vercel (the team behind Next.js and Webpack), it’s designed as the successor to Webpack.

Performance

Webpack (large app):

  • Cold start: 16s
  • HMR: ~500ms

Turbopack:

  • Cold start: 4s (4x faster)
  • HMR: ~10ms (50x faster)

Why So Fast?

  1. Written in Rust - Native performance
  2. Incremental computation - Only rebuilds what changed
  3. Optimized caching - Function-level memoization
  4. Lazy bundling - Only bundles requested modules

1. Getting Started

Turbopack is built into Next.js 13+:

npx create-next-app@latest my-app
cd my-app

Enable Turbopack

# Development with Turbopack
npm run dev -- --turbo

# Or update package.json
{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

2. Features

Automatic Configuration

No config needed! Turbopack automatically handles:

  • ✅ TypeScript
  • ✅ JSX/TSX
  • ✅ CSS/SCSS
  • ✅ CSS Modules
  • ✅ PostCSS
  • ✅ Images
  • ✅ Fonts
  • ✅ JSON

Hot Module Replacement

// app/page.tsx
export default function Page() {
  return <div>Hello, Turbopack!</div>;
}

// Edit and save - updates in ~10ms!

Code Splitting

Automatic code splitting:

// Automatically creates separate chunk
const Heavy = dynamic(() => import('./HeavyComponent'));

3. CSS Support

Plain CSS

/* styles.css */
.button {
  background: blue;
}
import './styles.css';

export default function Button() {
  return <button className="button">Click</button>;
}

CSS Modules

/* Button.module.css */
.button {
  background: blue;
}
import styles from './Button.module.css';

export default function Button() {
  return <button className={styles.button}>Click</button>;
}

Tailwind CSS

// tailwind.config.js
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}'
  ]
};

Works automatically with Turbopack!

SCSS/SASS

npm install sass
// styles.scss
$primary: blue;

.button {
  background: $primary;
}
import './styles.scss';

4. Image Optimization

Next.js Image optimization works with Turbopack:

import Image from 'next/image';
import logo from './logo.png';

export default function Page() {
  return <Image src={logo} alt="Logo" width={200} height={200} />;
}

5. Environment Variables

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://...
export default function Page() {
  // Client-side (NEXT_PUBLIC_ prefix)
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  
  return <div>{apiUrl}</div>;
}

6. Incremental Computation

Turbopack’s secret sauce: function-level memoization

// Component A changes
function ComponentA() {
  return <div>Changed!</div>;
}

// Component B doesn't change - Turbopack SKIPS rebuilding it
function ComponentB() {
  return <div>Unchanged</div>;
}

Traditional bundlers: Rebuild entire bundle Turbopack: Only rebuild ComponentA

7. Performance Comparison

Large App (30k modules)

BundlerCold StartHMR
Webpack 552s2.3s
Vite3.1s~100ms
Turbopack1.8s~10ms

Medium App (1k modules)

BundlerCold StartHMR
Webpack 516s500ms
Vite1.2s~50ms
Turbopack700ms~5ms

8. Next.js Integration

App Router

// app/page.tsx
export default function Home() {
  return <h1>Hello, Turbopack!</h1>;
}

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

Server Components

// app/users/page.tsx (Server Component)
async function getUsers() {
  const res = await fetch('https://api.example.com/users');
  return res.json();
}

export default async function UsersPage() {
  const users = await getUsers();
  
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

API Routes

// app/api/users/route.ts
export async function GET() {
  const users = await db.user.findMany();
  return Response.json({ users });
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.user.create({ data: body });
  return Response.json({ user }, { status: 201 });
}

9. Debugging

# Verbose logging
NEXT_TURBOPACK_LOG_LEVEL=trace npm run dev -- --turbo

# Debug output
DEBUG=turbopack:* npm run dev -- --turbo

10. Best Practices

1. Use for Development Only (Currently)

{
  "scripts": {
    "dev": "next dev --turbo",
    "build": "next build"
  }
}

2. Monitor Memory Usage

Turbopack uses more memory for caching:

NODE_OPTIONS='--max-old-space-size=4096' npm run dev -- --turbo

3. Clear Cache on Issues

rm -rf .next
npm run dev -- --turbo

11. Known Limitations (2026)

Currently Supported

  • ✅ TypeScript/JavaScript
  • ✅ CSS/SCSS/CSS Modules
  • ✅ Images and fonts
  • ✅ App Router
  • ✅ Server Components
  • ✅ API Routes

Coming Soon

  • ⏳ Production builds
  • ⏳ Webpack loader compatibility
  • ⏳ Standalone CLI
  • ⏳ Plugin system

12. Migration from Webpack

Step 1: Update Next.js

npm install next@latest

Step 2: Enable Turbopack

{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

Step 3: Test Your App

npm run dev

Most apps work immediately!

Step 4: Check Compatibility

// next.config.js
module.exports = {
  // Some webpack config may not work with Turbopack yet
  experimental: {
    turbo: {
      // Turbopack-specific config (optional)
    }
  }
};

Summary

Turbopack is the future of JavaScript bundling:

  • 10x faster than Webpack
  • Written in Rust for native speed
  • Incremental computation - only rebuild what changed
  • Built into Next.js 13+
  • Zero configuration required

Key Takeaways:

  1. 10x faster HMR than Webpack
  2. Incremental computation engine
  3. Built for Next.js (production support coming)
  4. Written in Rust for native speed
  5. Zero config, works out of the box

Next Steps:

Resources: