Настройка бандлера 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-сборка — в active development, поддержка появилась в 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 дня в зависимости от сложности кастомизаций.