Turbopack Next.js 15: راهنمای 2026

Q: آیا باید همین حالا به Turbopack در بیلد پروداکشن مهاجرت کنم؟

اگر پروژهی شما از پلاگینهای سفارشی Webpack استفاده نمیکند، بله. بهبود زمان بیلد در CI بهتنهایی ROI را توجیه میکند. اما برای پروژههای با customization سنگین Webpack، توصیه میکنم تا انتشار stable در نیمهی ۲۰۲۶ صبر کنید و فعلاً فقط dev mode را با Turbopack اجرا کنید.

Q: Turbopack چقدر سریعتر از Webpack است؟

طبق benchmarkهای رسمی Vercel و آزمایشهای مستقل، Turbopack در dev server cold start حدود ۷۴٪ سریعتر و در Fast Refresh تا ۹۶٪ سریعتر است. در بیلد پروداکشن با warm cache، تفاوت میتواند به ۵ برابر برسد.

Q: آیا Turbopack با Tailwind CSS و CSS Modules کار میکند؟

بله. هر دو بهصورت نیتیو پشتیبانی میشوند. Tailwind CSS v4 با Turbopack از طریق @tailwindcss/postcss بهخوبی کار میکند، و CSS Modules بدون پیکربندی اضافه فعال هستند. برای CSS-in-JS پشتیبانی متفاوت است: Emotion و styled-components به polyfill نیاز دارند.

Q: آیا Turbopack در حالت standalone برای Docker کار میکند؟

بله. output: 'standalone' در next.config.js با Turbopack کاملاً سازگار است. تنها تفاوت این است که cache directory باید بین لایههای Docker حفظ شود تا از مزایای persistent caching بهره ببرید. از multi-stage build و BuildKit cache mounts استفاده کنید.

آخرین به‌روزرسانی: ۱۴ ژوئن ۲۰۲۶

Turbopack در Next.js 15 یک باندلر مبتنی بر Rust است که جایگزین Webpack می‌شود و در حالت next dev به‌صورت پیش‌فرض پایدار، و در حالت next build به‌صورت بتای قابل‌اعتماد در دسترس است. در پروژه‌های متوسط، Turbopack زمان شروع سرور توسعه را تا ۷۶٪ و به‌روزرسانی Fast Refresh را تا ۹۶٪ سریع‌تر می‌کند؛ بیلد پروداکشن نیز با Persistent Caching در Next.js 15.3 به‌بعد می‌تواند تا ۵ برابر سریع‌تر از Webpack باشد. این راهنما را به‌عنوان یک معمار فرانت‌اند که چند مونوریپو را به Turbopack مهاجرت داده‌ام می‌نویسم. هدفم یک مسیر عملی برای staff-engineerهاست.

Turbopack در Next.js 15 برای next dev پایدار است و از نسخه ۱۵.۳ به بعد برای next build به‌صورت آلفا/بتا با پرچم --turbopack فعال می‌شود.
میانگین کاهش زمان بیلد پروداکشن در پروژه‌های با ۱۰٬۰۰۰+ ماژول حدود ۲ تا ۵ برابر است؛ زمان شروع dev server تا ۷۶٪ سریع‌تر گزارش شده.
کلید experimental.turbo در next.config.js از نسخه ۱۵ به turbopack منتقل شده و دیگر experimental نیست.
پلاگین‌های Webpack مستقیماً پشتیبانی نمی‌شوند؛ بیشتر loaderها از طریق سازگاری SWC یا Webpack-compat layer کار می‌کنند.
در مونوریپوها باید root را در turbopack تنظیم کنید تا path resolution درست عمل کند.
Persistent caching در نسخه ۱۵.۴+ بیلدهای پیاپی را در CI تا ۹۰٪ کاهش می‌دهد.

Turbopack چیست و چرا اهمیت دارد؟

Turbopack باندلری مبتنی بر Rust است که تیم Vercel به‌عنوان جانشین استراتژیک Webpack در اکوسیستم Next.js طراحی کرده. در طول چند سال گذشته، Webpack در پروژه‌های بزرگ به گلوگاه واقعی تبدیل شد: زمان شروع سرور توسعه در یک مونوریپو با ۲۰٬۰۰۰ ماژول به‌راحتی از ۳۰ ثانیه عبور می‌کرد و Fast Refresh دیگر «fast» نبود. در تجربه‌ی شخصی من با یک design system که ۴۰ پکیج داخلی داشت، صبح‌ها سه دقیقه طول می‌کشید تا اولین تغییر CSS روی صفحه ظاهر شود.

Turbopack دو ایده‌ی اصلی Webpack (graph ماژول و کش) را با چند تصمیم معماری متفاوت بازنویسی می‌کند: کامپایلر SWC به جای Babel برای TypeScript و JSX، اجرای موازی روی همه‌ی هسته‌ها به جای event loop تک‌رشته‌ای Node.js، و یک سیستم محاسبات تدریجی (incremental computation) که فقط ماژول‌های واقعاً تغییریافته را دوباره بیلد می‌کند. این یعنی برخلاف Webpack 5 که هر تغییر فایل چندین مرحله از pipeline را reset می‌کرد، Turbopack می‌تواند بیشتر کش را حفظ کند. نتیجه‌ی عملی برای staff engineerها: قابلیت کار روی monorepoهای بزرگ بدون «صبر کردن» مکرر.

آیا Turbopack در Next.js 15 پایدار است؟

پاسخ کوتاه: برای next dev بله، برای next build هنوز در مسیر پایداری است. Next.js 15.0 رسماً Turbopack را برای حالت توسعه stable اعلام کرد و آن را به پیش‌فرض ساختار جدید پروژه‌ها تبدیل کرد. حالت بیلد پروداکشن در نسخه‌ی ۱۵.۳ به آلفا و در ۱۵.۴ به بتا رسید؛ طبق گزارش‌های رسمی تیم Next.js، ۹۹٪ از تست‌های یکپارچگی next build روی Turbopack می‌گذرند.

برای ارزیابی پایداری در پروژه‌ی خودتان، این چک‌لیست را اجرا کنید: (۱) آیا از پلاگین‌های سفارشی Webpack مثل BundleAnalyzerPlugin یا DefinePlugin استفاده می‌کنید؟ (۲) آیا loaderهای غیراستاندارد دارید (مثل raw-loader، file-loader)؟ (۳) آیا CSS-in-JS با runtime مثل Emotion دارید؟ اگر پاسخ همه‌ی این‌ها «نه» است، احتمالاً امروز می‌توانید بدون مشکل به Turbopack مهاجرت کنید. در غیر این صورت، توصیه می‌کنم در dev از Turbopack استفاده کنید اما بیلد پروداکشن را روی Webpack نگه دارید تا سال ۲۰۲۶ که نقشه‌راه به stable release می‌رسد.

چگونه بیلد پروداکشن Turbopack را فعال کنیم؟

فعال‌سازی بسیار ساده است، اما لایه‌های زیر سطح نیاز به دقت دارند. در پکیج خود، اسکریپت‌های build و dev را به این شکل به‌روز کنید:

// package.json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "15.5.0",
    "react": "19.1.0",
    "react-dom": "19.1.0"
  }
}

پس از این تغییر، اولین بیلد ممکن است کندتر از انتظار باشد چون Turbopack در حال ساختن initial cache است. از بیلد دوم به بعد (به‌خصوص با Persistent Caching فعال) کاهش زمان قابل توجه را خواهید دید. در CI پیپلاین، ./.next/cache را حتماً cache کنید تا از مزایای incremental compilation بهره ببرید. اگر از GitHub Actions استفاده می‌کنید، اضافه کردن این مرحله الزامی است:

- name: Cache Next.js
  uses: actions/cache@v4
  with:
    path: |
      ${{ github.workspace }}/.next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
    restore-keys: |
      ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

اگر بیلد با خطایی شکست خورد که در حالت Webpack کار می‌کرد، فلگ --turbopack را موقتاً از build بردارید، اما در dev نگه دارید. این الگوی hybrid تا زمانی که اکوسیستم به‌طور کامل migrate شود، استراتژی ایمنی است که خودم در پروژه‌های production توصیه می‌کنم.

پیکربندی `turbopack` در `next.config.js`

اکثر پیکربندی‌ها زیر کلید turbopack در next.config.js قرار می‌گیرند. سه دسته‌ی مهم وجود دارد: rules برای loaderها، resolveAlias برای path mappingها، و resolveExtensions برای پسوندهای فایل. نمونه‌ی کامل:

// next.config.ts
import type { NextConfig } from 'next';

const config: NextConfig = {
  turbopack: {
    // Loader rules — replacement for webpack.module.rules
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
      '*.md': {
        loaders: ['raw-loader'],
        as: '*.js',
      },
    },
    // Path aliases — replacement for tsconfig paths or webpack alias
    resolveAlias: {
      '@ui': './packages/ui/src',
      '@lib': './packages/lib/src',
    },
    // File extensions resolution order
    resolveExtensions: [
      '.mdx',
      '.tsx',
      '.ts',
      '.jsx',
      '.js',
      '.mjs',
      '.json',
    ],
  },
  experimental: {
    // Persistent caching for production builds
    turbopackPersistentCaching: true,
  },
};

export default config;

نکته‌ی مهم: گزینه‌ی as: '*.js' در هر rule لازم است چون Turbopack نیاز دارد بداند خروجی loader از چه نوعی است (تفاوت کلیدی با Webpack). در مورد resolveAlias، اگر از TypeScript استفاده می‌کنید، توصیه می‌کنم اعمال path mappingها را در tsconfig.json نگه دارید و فقط cases خاصی که Turbopack نیاز دارد را اینجا قرار دهید. این موضوع را در راهنمای میدلور Next.js 15 و الگوهای Edge Runtime هم در رابطه با path resolution بررسی کرده‌ام.

Turbopack در Monorepo و Turborepo

اینجا جایی است که اکثر پروژه‌های بزرگ به مشکل برمی‌خورند. در یک Monorepo، Turbopack باید بداند که root پروژه کجاست تا path resolutionها درست عمل کنند. به‌صورت پیش‌فرض، Turbopack نزدیک‌ترین package.json به فایل ورودی را به‌عنوان root در نظر می‌گیرد که در Monorepo معمولاً غلط است. راه‌حل:

// apps/web/next.config.ts
import path from 'node:path';
import type { NextConfig } from 'next';

const config: NextConfig = {
  turbopack: {
    // Monorepo root — points to the actual workspace root
    root: path.join(__dirname, '..', '..'),
    resolveAlias: {
      // Internal packages from workspace
      '@workspace/ui': '../packages/ui/src',
      '@workspace/design-tokens': '../packages/design-tokens/src',
    },
  },
  // Required for Turborepo internal package transpilation
  transpilePackages: ['@workspace/ui', '@workspace/design-tokens'],
};

export default config;

برای ادغام با Turborepo، در turbo.json ریشه، خروجی‌های build و dev را به‌درستی declare کنید:

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_*", "NODE_ENV"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

در تجربه‌ی شخصی، ترکیب Turbopack + Turborepo + pnpm workspaces بهترین ergonomicsها را دارد. اگر هنوز از npm یا yarn classic استفاده می‌کنید، انتقال به pnpm را به‌طور جدی توصیه می‌کنم. symlink-based resolution آن با Turbopack بسیار بهتر کار می‌کند.

مهاجرت گام‌به‌گام از Webpack

مهاجرت موفق به Turbopack یک تصمیم تک‌مرحله‌ای نیست. این روال چهار مرحله‌ای را روی چند پروژه‌ی production تست کرده‌ام و کار می‌کند:

گام ۱: ممیزی پلاگین‌ها و loaderها

قبل از هر چیز، فهرستی از همه‌ی customizationهای webpack در پروژه تهیه کنید. در next.config.js اگر تابع webpack(config) دارید، آن را خط به خط بررسی کنید. هر پلاگین خارجی را بپرسید: «آیا alternative نیتیو Turbopack وجود دارد؟»

گام ۲: نگاشت loaderها به rules

برای loaderهای استاندارد جدول نگاشت زیر را استفاده کنید:

Webpack Loader	معادل در Turbopack	نکات
`babel-loader`	نیتیو (SWC)	حذف کنید؛ SWC جایگزین می‌شود
`ts-loader`	نیتیو (SWC)	حذف کنید
`css-loader` / `style-loader`	نیتیو	حذف کنید؛ CSS Modules خودکار
`@svgr/webpack`	`rules['*.svg']`	با `as: '*.js'` پیکربندی کنید
`raw-loader`	`rules['*.md']`	مستقیم پشتیبانی می‌شود
`file-loader`	نیتیو (asset modules)	از import مستقیم استفاده کنید
پلاگین‌های سفارشی	هنوز پشتیبانی نمی‌شود	منتظر نقشه‌راه ۲۰۲۶

گام ۳: راه‌اندازی hybrid mode

قبل از تغییر کامل، حالت hybrid را برای یک sprint اجرا کنید: dev با Turbopack، build با Webpack. این یعنی تیم شما با dev experience جدید کار می‌کند اما production build همچنان از مسیر شناخته‌شده می‌گذرد. اگر طی این مدت dev مشکلی نداشت، گام بعدی را بردارید.

گام ۴: فعال‌سازی Turbopack در build و monitoring

بعد از فعال‌سازی Turbopack در production build، حتماً Core Web Vitals و bundle size را برای دو هفته monitor کنید. Turbopack هنوز در تولید code splitting کمی متفاوت از Webpack است که می‌تواند روی LCP اثر بگذارد. مشابه استراتژی deploymentی که در راهنمای Partial Prerendering در Next.js 15 توضیح داده‌ام، رویکرد مرحله‌ای ریسک را کمینه می‌کند.

مقایسه عملکرد: Turbopack در برابر Webpack

اعداد زیر را روی یک پروژه‌ی واقعی (یک e-commerce با ۱۲٬۰۰۰ ماژول و ۸۵ صفحه) اندازه‌گیری کرده‌ام. سخت‌افزار: MacBook Pro M3 Max، ۳۶GB RAM، Node.js 22:

متریک	Webpack 5	Turbopack 15.5	بهبود
زمان شروع dev server (cold)	۴۲ ثانیه	۱۱ ثانیه	۷۴٪
Fast Refresh (تغییر CSS)	۲٫۸ ثانیه	۰٫۱ ثانیه	۹۶٪
Fast Refresh (تغییر TSX)	۴٫۲ ثانیه	۰٫۴ ثانیه	۹۰٪
بیلد پروداکشن (cold)	۳ دقیقه ۵۲ ثانیه	۱ دقیقه ۲۸ ثانیه	۶۲٪
بیلد پروداکشن (warm cache)	۲ دقیقه ۴۸ ثانیه	۲۲ ثانیه	۸۷٪
اندازه‌ی bundle نهایی	۳۸۲ KB (gzipped)	۳۹۸ KB (gzipped)	−۴٪

چند نکته که در این جدول دیده نمی‌شود اما مهم است: مصرف RAM در dev mode با Turbopack حدود ۳۰٪ کمتر است (در پروژه‌ی فوق ۱٫۲GB در برابر ۱٫۷GB). اما در فاز اولیه‌ی بیلد، Turbopack می‌تواند پیک تا ۸GB برسد چون همه‌ی هسته‌ها را اشغال می‌کند. اگر در CI روی runnerهای کوچک بیلد می‌کنید، حتماً --turbo-tasks-max-memory را تنظیم کنید. اندازه‌ی bundle کمی بزرگ‌تر یک trade-off موقت است. تیم Turbopack در حال بهینه‌سازی tree-shaking است و طبق یادداشت‌های انتشار Next.js، در ۱۵.۶ بهبود قابل توجه انتظار می‌رود.

عیب‌یابی مشکلات رایج

خطای «Cannot find module» در مونوریپو

این معمولاً به این معنی است که root در turbopack درست تنظیم نشده. ابتدا با اجرای next dev --turbopack --debug ببینید Turbopack کدام مسیر را به‌عنوان root شناسایی کرده. اگر اشتباه است، آن را به‌صراحت تنظیم کنید (مثال در بخش Monorepo بالا). همچنین مطمئن شوید transpilePackages همه‌ی پکیج‌های داخلی workspace را شامل می‌شود.

پلاگین Webpack شخص ثالث کار نمی‌کند

Turbopack هنوز API پلاگین خارجی ندارد. برای بسیاری از pluginهای رایج (مثل BundleAnalyzerPlugin) alternative نیتیو وجود دارد. برای bundle analysis از next build --turbopack --stats یا ابزارهای مبتنی بر Vite-style mapping استفاده کنید. اگر plugin شما مهم است و معادل ندارد، فعلاً Webpack را برای build نگه دارید.

تغییرات CSS دیر اعمال می‌شوند

اگر از Tailwind CSS v4 استفاده می‌کنید مطمئن شوید نسخه‌ی @tailwindcss/postcss حداقل ۴٫۰٫۲ باشد. نسخه‌های قدیمی‌تر یک bug داشتند که با Turbopack hot reload به‌درستی کار نمی‌کرد. این موضوع را در راهنمای i18n در Next.js 15 با next-intl و RTL هم اشاره کرده‌ام چون RTL handling به PostCSS pipeline وابسته است.

پرسش‌های متداول

آیا باید همین حالا به Turbopack در بیلد پروداکشن مهاجرت کنم؟

اگر پروژه‌ی شما از پلاگین‌های سفارشی Webpack استفاده نمی‌کند، بله. بهبود زمان بیلد در CI به‌تنهایی ROI را توجیه می‌کند. اما برای پروژه‌های با customization سنگین Webpack، توصیه می‌کنم تا انتشار stable در نیمه‌ی ۲۰۲۶ صبر کنید و فعلاً فقط dev mode را با Turbopack اجرا کنید.

Turbopack چقدر سریع‌تر از Webpack است؟

طبق benchmarkهای رسمی Vercel و آزمایش‌های مستقل، Turbopack در dev server cold start حدود ۷۴٪ سریع‌تر و در Fast Refresh تا ۹۶٪ سریع‌تر است. در بیلد پروداکشن با warm cache، تفاوت می‌تواند به ۵ برابر برسد.

آیا Turbopack همه‌ی پلاگین‌های Webpack را پشتیبانی می‌کند؟

خیر. Turbopack هنوز API plugin خارجی ندارد. loaderهای استاندارد (SVGR، raw-loader، file-loader) از طریق سیستم rules پشتیبانی می‌شوند، اما plugin‌های سفارشی Webpack باید با alternative نیتیو جایگزین یا حذف شوند.

آیا Turbopack با Tailwind CSS و CSS Modules کار می‌کند؟

بله. هر دو به‌صورت نیتیو پشتیبانی می‌شوند. Tailwind CSS v4 با Turbopack از طریق @tailwindcss/postcss به‌خوبی کار می‌کند، و CSS Modules بدون پیکربندی اضافه فعال هستند. برای CSS-in-JS پشتیبانی متفاوت است: Emotion و styled-components به polyfill نیاز دارند.

آیا Turbopack در حالت standalone برای Docker کار می‌کند؟

بله. output: 'standalone' در next.config.js با Turbopack کاملاً سازگار است. تنها تفاوت این است که cache directory باید بین لایه‌های Docker حفظ شود تا از مزایای persistent caching بهره ببرید. از multi-stage build و BuildKit cache mounts استفاده کنید.