Налаштування бандлера Turbopack для веб-проекту

Налаштування бандлера Turbopack для веб-проекту

Turbopack — збирач від Vercel, написаний на Rust, розроблений як наступник Webpack всередині Next.js. На стан на 2025 рік він стабільний для dev-режиму в Next.js 13+ та поступово набирає підтримку production-побудови. Прямое використання поза Next.js поки обмежено.

Поточний статус

Turbopack не існує як standalone-інструмент з відкритим API конфіги — на відміну від Webpack, Vite або esbuild. Він інтегрований в Next.js через флаг --turbopack і конфігурується через next.config.ts. Це свідомі рішення команди: спочатку стабілізувати всередину одного фреймворку, потім розширювати підтримку.

На що розраховувати:

• dev-режим — стабільний з Next.js 14+, помітний приріст швидкості при великих кодових базах
• production-побудова — в активній розробці, підтримка з'явилась у Next.js 15 в експериментальному режимі
• standalone використання — поки недоступно публічно

Включення в Next.js

# Next.js 14+
next dev --turbopack

# Або через package.json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build"  // production поки без флаги
  }
}

Конфігурація через next.config.ts

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

const config: NextConfig = {
  experimental: {
    turbo: {
      // Кастомні лоадери (аналог webpack loaders)
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        '*.mdx': {
          loaders: ['@mdx-js/loader'],
          as: '*.js',
        },
      },

      // Алія шляхів
      resolveAlias: {
        '@components': './src/components',
        '@utils': './src/utils',
        // Заміна модулів (аналог webpack resolve.alias)
        'lodash': 'lodash-es',
      },

      // Розширення файлів в порядку пріоритету
      resolveExtensions: ['.tsx', '.ts', '.jsx', '.js', '.json'],
    },
  },
};

export default config;

Сумісність з webpack loaders

Turbopack підтримує обмежений набір webpack-сумісних лоадерів. Повністю сумісні:

rules: {
  '*.mdx': { loaders: ['@mdx-js/loader'], as: '*.js' },
  '*.svg': { loaders: ['@svgr/webpack'], as: '*.js' },
  '*.yaml': { loaders: ['yaml-loader'], as: '*.js' },
  '*.graphql': { loaders: ['graphql-tag/loader'], as: '*.js' },
}

Не працюють або працюють частково: більшість CSS-loaders (Next.js обробляє CSS своїми засобами), лоадери зі складними side-effects, лоадери що потребують webpack compilation hooks.

Змінні окружння та define

// У next.config.ts Turbopack враховує стандартні Next.js env
// .env.local, .env.development, .env.production

// Для кастомних define немає прямого API в Turbopack —
// використовуйте стандартний механізм Next.js:
const config: NextConfig = {
  env: {
    CUSTOM_KEY: process.env.CUSTOM_KEY,
  },
};

Відладка продуктивності

Turbopack має вбудований трейсинг:

NEXT_TURBOPACK_TRACING=1 next dev --turbopack

Генерує .next/trace файл, який можна відкрити в Chrome DevTools Performance tab через chrome://tracing.

Корисні метрики які варто відстежувати після включення Turbopack:

# Час першого запуску dev-сервера
time next dev --turbopack

# Час HMR після змін файлу — дивіться в терміналі:
# "compiled client and server successfully in Xms"

Обмеження щодо Webpack

На поточний момент в Next.js з Turbopack недоступні:

• webpack() функція в next.config.ts ігнорується
• Деякі плагіни Babel (Turbopack використовує SWC)
• next/bundle-analyzer — заміна: @next/bundle-analyzer не працює, використовуйте turbo-pack-analyze або вбудований tracing
• Частина community-плагінів які пачать webpack конфіг напрямки

// Це не буде працювати з --turbopack:
const config: NextConfig = {
  webpack(config) {
    config.plugins.push(new MyPlugin());  // ігнорується
    return config;
  },
};

Міграція з webpack-кастомізацій

Якщо проект використовує нестандартні webpack-конфіги, перед включенням Turbopack варто провести аудит:

# Перевірити що використовується в webpack конфігу
grep -r "webpack(" next.config.*
grep -r "new webpack\." next.config.*

Для кожної кастомізації потрібно знайти аналог в Turbopack API або тимчасово залишити webpack для production:

// Гібридний підхід: Turbopack для dev, Webpack для build
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build"  // webpack
  }
}

Терміни

Включення --turbopack в існуючому Next.js проекті без кастомних webpack-лоадерів: 1–2 години (включаючи тестування та перевірку сумісності). Міграція проекту з нестандартними webpack-конфігами: 1–3 дні залежно від складності кастомізацій.