Contrarian View: You Don't Need Turbopack 3.0 for Next.js 16 – Vite 5.0 Is Fast Enough

// vite.config.ts - Vite 5.0 configuration for Next.js 16
// Imports: Vite core, Next.js plugin, React plugin, image optimization
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { ViteNextPlugin } from 'vite-plugin-next'; // Community-maintained Next.js 16 compatibility plugin
import { ViteImageOptimizer } from 'vite-plugin-image-optimizer';
import path from 'path';
import { fileURLToPath } from 'url';

// Resolve __dirname for ESM modules
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Validate required environment variables at config load time
const validateEnv = () => {
  const required = ['NEXT_PUBLIC_API_URL', 'NEXT_PUBLIC_ASSET_PREFIX'];
  const missing = required.filter(key => !process.env[key]);
  if (missing.length > 0) {
    throw new Error(`Missing required env vars: ${missing.join(', ')}`);
  }
};

// Run validation
try {
  validateEnv();
} catch (err) {
  console.error('[Vite Config] Environment validation failed:', err.message);
  process.exit(1);
}

export default defineConfig(({ command, mode }) => {
  // Log current build mode for debugging
  console.log(`[Vite Config] Running in ${mode} mode, command: ${command}`);

  // Base configuration shared between dev and build
  const baseConfig = {
    plugins: [
      // React plugin with fast refresh and Babel fallback
      react({
        babel: {
          plugins: [['babel-plugin-react-compiler']], // Enable React Compiler for Next.js 16
        },
        fastRefresh: true,
      }),
      // Next.js 16 compatibility plugin: handles App Router, RSC, and metadata
      ViteNextPlugin({
        appDir: path.resolve(__dirname, 'src/app'), // Next.js 16 App Router directory
        pageExtensions: ['tsx', 'ts', 'jsx', 'js'],
        experimental: {
          serverActions: true, // Enable Next.js 16 Server Actions
          ppr: 'incremental', // Partial Prerendering support
        },
      }),
      // Image optimization plugin matching Next.js 16 image standards
      ViteImageOptimizer({
        gif: { optimizationLevel: 7 },
        jpeg: { quality: 80 },
        jpg: { quality: 80 },
        png: { quality: 80 },
        svg: { cleanupIDs: false },
        webp: { quality: 75 },
        avif: { quality: 70 },
      }),
    ],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src'), // Absolute import alias
        '@components': path.resolve(__dirname, 'src/components'),
        '@lib': path.resolve(__dirname, 'src/lib'),
      },
    },
    build: {
      outDir: path.resolve(__dirname, '.next'), // Output to Next.js 16 default build directory
      rollupOptions: {
        output: {
          // Chunk splitting for optimal Next.js 16 bundle size
          manualChunks: {
            'react-vendor': ['react', 'react-dom', 'react-router-dom'],
            'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
            'utils': ['lodash', 'date-fns'],
          },
        },
      },
      target: 'esnext', // Next.js 16 targets modern browsers
      sourcemap: mode === 'development', // Sourcemaps only in dev
    },
    server: {
      port: 3000, // Match Next.js 16 default port
      proxy: {
        // Proxy API requests to backend in development
        '/api': {
          target: process.env.NEXT_PUBLIC_API_URL,
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, ''),
          configure: (proxy, options) => {
            // Handle proxy errors
            proxy.on('error', (err, req, res) => {
              console.error('[Vite Proxy] Error:', err.message);
              if (!res.headersSent) {
                res.writeHead(500, { 'Content-Type': 'application/json' });
                res.end(JSON.stringify({ error: 'Proxy error', message: err.message }));
              }
            });
          },
        },
      },
    },
  };

  // Add mode-specific config
  if (mode === 'development') {
    return {
      ...baseConfig,
      server: {
        ...baseConfig.server,
        hmr: { overlay: true }, // Enable HMR overlay
      },
    };
  }

  // Production config
  return {
    ...baseConfig,
    build: {
      ...baseConfig.build,
      minify: 'terser', // Terser for smaller production bundles
      terserOptions: {
        compress: {
          drop_console: true, // Remove console logs in production
        },
      },
    },
  };
});

// next.config.ts - Turbopack 3.0 configuration for Next.js 16
// Imports: Next.js config types, Turbopack-specific plugins
import type { NextConfig } from 'next';
import type { TurbopackConfig } from '@turbo/types';
import path from 'path';
import { fileURLToPath } from 'url';

// Resolve __dirname for ESM modules
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Validate required environment variables at config load time
const validateEnv = () => {
  const required = ['NEXT_PUBLIC_API_URL', 'NEXT_PUBLIC_ASSET_PREFIX'];
  const missing = required.filter(key => !process.env[key]);
  if (missing.length > 0) {
    throw new Error(`Missing required env vars: ${missing.join(', ')}`);
  }
};

// Run validation
try {
  validateEnv();
} catch (err) {
  console.error('[Next.js Config] Environment validation failed:', err.message);
  process.exit(1);
}

// Turbopack 3.0 specific configuration
const turbopackConfig: TurbopackConfig = {
  rules: [
    // Handle image files with Turbopack's built-in image optimizer
    {
      test: /\.(png|jpg|jpeg|gif|webp|avif|svg)$/,
      loader: '@turbo/image-loader',
      options: {
        quality: 80,
        formats: ['webp', 'avif'],
        fallbackFormat: 'jpeg',
      },
    },
    // Handle CSS modules with Turbopack's CSS loader
    {
      test: /\.module\.css$/,
      loader: '@turbo/css-loader',
      options: {
        modules: {
          localIdentName: '[name]__[local]___[hash:base64:5]',
        },
      },
    },
  ],
  resolveAlias: {
    '@': path.resolve(__dirname, 'src'),
    '@components': path.resolve(__dirname, 'src/components'),
    '@lib': path.resolve(__dirname, 'src/lib'),
  },
  experimental: {
    enableTurbopackProfiling: false, // Disable profiling in production
  },
};

const nextConfig: NextConfig = {
  // Enable Turbopack 3.0 as the default bundler
  turbopack: turbopackConfig,
  // Next.js 16 App Router configuration
  appDir: true,
  pageExtensions: ['tsx', 'ts', 'jsx', 'js'],
  // Image optimization configuration (Turbopack 3.0 compatible)
  images: {
    domains: [new URL(process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000').hostname],
    formats: ['image/webp', 'image/avif'],
    minimumCacheTTL: 60,
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
  // React configuration for Next.js 16
  react: {
    compiler: true, // Enable React Compiler
    strictMode: true,
  },
  // Experimental Next.js 16 features
  experimental: {
    serverActions: true,
    ppr: 'incremental',
    missingSuspenseWithCSRBailout: false,
  },
  // Webpack fallback (Turbopack 3.0 still uses Webpack for some edge cases)
  webpack: (config, { isServer, webpack }) => {
    // Add error handling for Webpack build errors
    config.plugins.push(
      new webpack.DefinePlugin({
        'process.env.NEXT_PUBLIC_BUILD_TIME': JSON.stringify(new Date().toISOString()),
      })
    );

    // Handle build errors
    config.stats = {
      ...config.stats,
      logging: 'verbose',
      errors: true,
      warnings: true,
    };

    // Alias configuration matching Turbopack
    config.resolve.alias = {
      ...config.resolve.alias,
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
      '@lib': path.resolve(__dirname, 'src/lib'),
    };

    return config;
  },
  // Proxy configuration for development
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: `${process.env.NEXT_PUBLIC_API_URL}/:path*`,
      },
    ];
  },
};

export default nextConfig;

// benchmark.ts - Benchmark script to compare Vite 5.0 and Turbopack 3.0 for Next.js 16
// Imports: puppeteer for browser testing, fs for file ops, child_process for running builds
import puppeteer from 'puppeteer';
import fs from 'fs/promises';
import path from 'path';
import { exec, spawn } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

// Configuration for benchmark runs
const BENCHMARK_CONFIG = {
  appUrl: 'http://localhost:3000',
  testRoutes: ['/', '/about', '/blog', '/products', '/contact'],
  buildIterations: 5,
  devColdStartIterations: 10,
  browser: 'chrome' as const,
};

// Utility to measure execution time
const measureTime = async (fn: () => Promise): Promise => {
  const start = performance.now();
  await fn();
  const end = performance.now();
  return end - start;
};

// Run a single build for a given bundler
const runBuild = async (bundler: 'vite' | 'turbopack'): Promise => {
  const buildCmd = bundler === 'vite' ? 'vite build' : 'next build';
  console.log(`[Benchmark] Running ${bundler} build...`);
  try {
    const { stderr } = await execAsync(buildCmd, { cwd: process.cwd() });
    if (stderr) console.error(`[Benchmark] ${bundler} build stderr:`, stderr);
    // Measure build time by running the build and timing it
    const buildTime = await measureTime(async () => {
      await execAsync(buildCmd, { cwd: process.cwd() });
    });
    return buildTime;
  } catch (err) {
    console.error(`[Benchmark] ${bundler} build failed:`, err.message);
    throw err;
  }
};

// Start dev server for a given bundler
const startDevServer = async (bundler: 'vite' | 'turbopack'): Promise<() => Promise> => {
  const startCmd = bundler === 'vite' ? 'vite' : 'next dev';
  console.log(`[Benchmark] Starting ${bundler} dev server...`);
  const server = spawn(startCmd, { cwd: process.cwd(), shell: true });

  // Wait for server to be ready
  await new Promise((resolve, reject) => {
    const timeout = setTimeout(() => {
      reject(new Error(`${bundler} dev server failed to start within 30s`));
    }, 30000);
    server.stdout.on('data', (data) => {
      const output = data.toString();
      if (output.includes('ready') || output.includes('Local:')) {
        clearTimeout(timeout);
        resolve();
      }
    });
    server.stderr.on('data', (data) => {
      console.error(`[Benchmark] ${bundler} dev stderr:`, data.toString());
    });
  });

  // Return stop function
  return async () => {
    console.log(`[Benchmark] Stopping ${bundler} dev server...`);
    server.kill('SIGTERM');
    await new Promise((resolve) => {
      server.on('close', resolve);
    });
  };
};

// Measure page load time for a route
const measurePageLoad = async (browser: puppeteer.Browser, route: string): Promise => {
  const page = await browser.newPage();
  try {
    const start = performance.now();
    await page.goto(`${BENCHMARK_CONFIG.appUrl}${route}`, { waitUntil: 'networkidle0' });
    const end = performance.now();
    return end - start;
  } catch (err) {
    console.error(`[Benchmark] Failed to load ${route}:`, err.message);
    return 0;
  } finally {
    await page.close();
  }
};

// Main benchmark function
const runBenchmark = async () => {
  console.log('[Benchmark] Starting Next.js 16 bundler benchmark...');
  const browser = await puppeteer.launch({ headless: true, browser: BENCHMARK_CONFIG.browser });
  const results = {
    vite: { buildTime: 0, coldStart: 0, pageLoad: {} as Record },
    turbopack: { buildTime: 0, coldStart: 0, pageLoad: {} as Record },
  };

  // Run benchmarks for each bundler
  for (const bundler of ['vite', 'turbopack'] as const) {
    console.log(`\n[Benchmark] Testing ${bundler}...`);

    // Measure build time (average over 5 iterations)
    let totalBuildTime = 0;
    for (let i = 0; i < BENCHMARK_CONFIG.buildIterations; i++) {
      const buildTime = await runBuild(bundler);
      totalBuildTime += buildTime;
      console.log(`[Benchmark] ${bundler} build ${i+1}: ${buildTime.toFixed(2)}ms`);
    }
    results[bundler].buildTime = totalBuildTime / BENCHMARK_CONFIG.buildIterations;

    // Measure cold start time (average over 10 iterations)
    let totalColdStart = 0;
    for (let i = 0; i < BENCHMARK_CONFIG.devColdStartIterations; i++) {
      const stopDev = await startDevServer(bundler);
      const coldStart = await measureTime(async () => {
        await startDevServer(bundler);
      });
      totalColdStart += coldStart;
      await stopDev();
      console.log(`[Benchmark] ${bundler} cold start ${i+1}: ${coldStart.toFixed(2)}ms`);
    }
    results[bundler].coldStart = totalColdStart / BENCHMARK_CONFIG.devColdStartIterations;

    // Measure page load times for test routes
    const stopDev = await startDevServer(bundler);
    for (const route of BENCHMARK_CONFIG.testRoutes) {
      const loadTime = await measurePageLoad(browser, route);
      results[bundler].pageLoad[route] = loadTime;
      console.log(`[Benchmark] ${bundler} load ${route}: ${loadTime.toFixed(2)}ms`);
    }
    await stopDev();
  }

  // Output results
  console.log('\n[Benchmark] Final Results:');
  console.log(JSON.stringify(results, null, 2));
  await fs.writeFile(path.resolve(__dirname, 'benchmark-results.json'), JSON.stringify(results, null, 2));
  await browser.close();
};

// Run benchmark with error handling
runBenchmark().catch(async (err) => {
  console.error('[Benchmark] Fatal error:', err.message);
  process.exit(1);
});

// Install the plugin
// npm install vite-plugin-next@1.2.0 -D
import { ViteNextPlugin } from 'vite-plugin-next';

export default defineConfig({
  plugins: [
    ViteNextPlugin({
      appDir: 'src/app',
      experimental: { serverActions: true, ppr: 'incremental' }
    })
  ]
});

// Vite 5 chunk splitting for Next.js 16
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom', 'next/router'],
          'dashboard': ['src/app/dashboard/*'], // Route-based splitting
          'marketing': ['src/app/(marketing)/*'],
        },
      },
    },
  },
});

// Vite 5 proxy configuration for Next.js 16
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: process.env.NEXT_PUBLIC_API_URL,
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
        configure: (proxy) => {
          proxy.on('error', (err) => console.error('Proxy error:', err));
        },
      },
    },
  },
});