@utoo/pack

🌖 High-performance bundler core for the Utoo toolchain, powered by Turbopack.

@utoo/pack is the engine behind the Utoo build system. It leverages the incremental computation power of Turbopack and the performance of Rust to provide a lightning-fast development and build experience.

✨ Key Features

• ⚡ Extreme Performance: Core bundling logic implemented in Rust via NAPI-RS.
• 🛠️ Turbopack Powered: Built on top of the same engine that powers Next.js Turbopack.
• 🔌 Webpack Compatibility: Support for consuming webpack.config.js to simplify migration from Webpack.
• 📦 Modern Web Support: Native support for TypeScript, JSX, CSS Modules, Less, Sass, and more.
• 🔧 Extensible Architecture: Support for custom loaders, plugins, and flexible configuration.
• 🔄 Fast HMR: Instant updates during development with optimized Hot Module Replacement.

✨ Supported Features

@utoo/pack aims for high compatibility with the Webpack ecosystem while providing superior performance.

• Entry: Supports name, import, and filename templates.
• Module Rules: Support for most mainstream Webpack loaders via loader-runner.
• Resolve: Full support for alias and extensions.
• Styles: Built-in support for Less, Sass, PostCSS, CSS Modules, and LightningCSS.
• Optimization: Minification, Tree Shaking, Module Concatenation, and more.
• Frameworks: Optimized for React (including styled-jsx, styled-components).
• Tools: Integrated Bundle Analyzer and Tracing Logs.

[!TIP] For a detailed status of all features, see the Features List.

📦 Installation

ut install @utoo/pack --save-dev

🚀 Quick Start

Programmatic API

You can use @utoo/pack directly in your Node.js scripts:

const { build, dev } = require('@utoo/pack');

// Production build
async function runBuild() {
  await build({
    config: {
      entry: [
        {
          import: "./src/index.ts",
          html: {
            template: "./index.html"
          }
        }
      ],
      output: {
        path: "./dist",
        filename: "[name].[contenthash:8].js",
        chunkFilename: "[name].[contenthash:8].js",
        clean: true
      },
      sourceMaps: true
    }
  });
}

// Development mode with HMR
async function startDev() {
  const server = await dev({
    config: {
      entry: [
        {
          import: "./src/index.ts",
          html: {
            template: "./index.html"
          }
        }
      ],
      output: {
        path: "./dist",
        filename: "[name].[contenthash:8].js",
        chunkFilename: "[name].[contenthash:8].js",
        clean: true
      },
      sourceMaps: true
    }
  });
}

🔌 Webpack Compatibility Mode

@utoo/pack provides a partial compatibility layer for Webpack.

const { build } = require('@utoo/pack');
const webpackConfig = require('./webpack.config.js');

async function run() {
  await build({ ...webpackConfig, webpackMode: true });
}

[!NOTE] Not all Webpack features and plugins are supported. Check the Features List for details on supported configuration options.

⚙️ Configuration

The bundler can be configured via a utoopack.json or through the programmatic API. Key configuration areas include:

• entry: Define your application entry points.
• define: Build-time variable replacement.
• externals: Exclude specific dependencies from the bundle.
• server.externals: Replace top-level externals for server entries and Server Functions. If omitted, server builds continue to use top-level externals.
• devServer.browserToTerminal: Forward browser console output to the development terminal. Use "error", "warn", true, or false; standalone Utoopack defaults to false.
• mode: development or production.

For a full list of options, see the Configuration Schema.

🛠️ Development

Prerequisites

• Rust: Nightly toolchain (see rust-toolchain.toml).
• Node.js: Version 20 or higher.

Building from Source

# Build Rust bindings and TypeScript modules
npm run build

📄 License

MIT