Configuration

@utoo/pack can be configured via utoopack.json, utoopack.config.mjs, or through the programmatic API.

Configuration Files

utoopack.json


{
  "$schema": "@utoo/pack/config_schema.json",
  "mode": "production",
  "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
}

Core Options

mode

Build mode, affects optimizations and defaults.

Value	Description
`development`	Faster builds, better debugging, HMR enabled
`production`	Optimized output, minification, tree shaking

entry

Define application entry points.


{
  "entry": [
    {
      "name": "main",
      "import": "./src/index.ts",
      "html": {
        "template": "./index.html",
        "filename": "index.html",
        "title": "My App",
        "inject": "body",
        "scriptLoading": "defer"
      },
      "library": {
        "name": "MyLib",
        "export": ["default"]
      }
    }
  ]
}

output

Configure output settings.


{
  "output": {
    "path": "./dist",
    "filename": "[name].[contenthash:8].js",
    "chunkFilename": "[name].[contenthash:8].js",
    "publicPath": "/",
    "clean": true,
    "copy": ["public"],
    "type": "standalone",
    "chunkLoadingGlobal": "TURBOPACK",
    "entryRootExport": "MyApp"
  }
}

Option	Description
`path`	Output directory
`filename`	Entry chunk filename template
`chunkFilename`	Non-entry chunk filename template
`cssFilename`	CSS filename template
`cssChunkFilename`	Non-entry CSS chunk filename template
`assetModuleFilename`	Asset module filename template
`publicPath`	Public URL path for assets
`clean`	Clean output directory before build
`copy`	Copy static files (string paths or `{ from, to }` objects)
`type`	Output type: `standalone` or `export`
`chunkLoadingGlobal`	Global variable name for loading chunks
`entryRootExport`	Expose entry exports to global scope

target

Target environment string (e.g., "web", "node").

define

Build-time variable replacement.


{
  "define": {
    "process.env.NODE_ENV": "\"production\"",
    "__VERSION__": "\"1.0.0\""
  }
}

externals

Exclude dependencies from the bundle.


{
  "externals": {
    "react": "React",
    "react-dom": "ReactDOM"
  }
}

Externals support simple string globals, UMD configuration, and advanced subpath configuration.

resolve

Module resolution configuration.


{
  "resolve": {
    "alias": {
      "@": "./src",
      "@components": "./src/components"
    },
    "extensions": [".ts", ".tsx", ".js", ".jsx"]
  }
}

module

Module rules and conditions for custom loaders.


{
  "module": {
    "rules": {
      "*.svg": "svgr-loader",
      "*.mdx": [
        { "loader": "mdx-loader", "options": {} }
      ]
    },
    "conditions": {
      "*.js": {
        "path": { "type": "glob", "value": "**/node_modules/**" }
      }
    }
  }
}

Option	Description
`rules`	Map glob patterns to loaders
`conditions`	Configure loader conditions by path (glob or regex)

provider

Auto-provide modules (similar to webpack ProvidePlugin).


{
  "provider": {
    "$": "jquery",
    "Buffer": ["buffer", "Buffer"]
  }
}

Optimization


{
  "optimization": {
    "minify": true,
    "treeShaking": true,
    "concatenateModules": true,
    "moduleIds": "deterministic",
    "removeConsole": true,
    "removeUnusedExports": true,
    "removeUnusedImports": true,
    "splitChunks": {
      "js": {
        "minChunkSize": 50000,
        "maxChunkCountPerGroup": 40,
        "maxMergeChunkSize": 200000
      }
    },
    "modularizeImports": {
      "lodash": {
        "transform": "lodash/{{member}}",
        "preventFullImport": true
      }
    },
    "packageImports": ["antd", "lodash-es"],
    "transpilePackages": ["my-local-package"],
    "nestedAsyncChunking": true,
    "wasmAsAsset": false
  }
}

Option	Description
`minify`	Enable code minification
`treeShaking`	Remove unused code
`concatenateModules`	Module concatenation (scope hoisting)
`moduleIds`	ID strategy: `named` or `deterministic`
`noMangling`	Disable name mangling
`removeConsole`	Remove console statements (`true` or `{ exclude: ["error"] }`)
`removeUnusedExports`	Remove unused exports
`removeUnusedImports`	Remove unused imports
`splitChunks`	Chunk splitting configuration
`modularizeImports`	Transform barrel imports (like `babel-plugin-import`)
`packageImports`	Packages to optimize imports for
`transpilePackages`	Transpile specific packages
`nestedAsyncChunking`	Enable nested async chunking
`wasmAsAsset`	Bundle WASM as asset

Styles


{
  "styles": {
    "autoCssModules": true,
    "emotion": true,
    "styledComponents": true,
    "styledJsx": true,
    "less": { "implementation": "less" },
    "sass": { "implementation": "sass" },
    "inlineCss": {
      "injectType": "styleTag"
    }
  }
}

Option	Description
`autoCssModules`	Auto-detect and apply CSS Modules
`emotion`	Enable @emotion/react transform
`styledComponents`	Enable styled-components transform (`true` or config object )
`styledJsx`	Enable styled-jsx transform (`true` or `{ useLightningcss: true }`)
`less`	Less preprocessor config (`implementation`, plus Less options)
`sass`	Sass/SCSS preprocessor config (`implementation`, plus Sass options)
`inlineCss`	CSS injection via style tags (`insert`, `injectType`)

Images


{
  "images": {
    "inlineLimit": 10000
  }
}

Option	Description
`inlineLimit`	Inline images smaller than this size (bytes) as base64

Development Server


{
  "devServer": {
    "hot": true,
    "port": 3000,
    "host": "localhost",
    "https": false
  }
}

Option	Description
`hot`	Enable Hot Module Replacement
`port`	Port to listen on
`host`	Host to bind
`https`	Use HTTPS

React


{
  "react": {
    "runtime": "automatic",
    "importSource": "react"
  }
}

Option	Description
`runtime`	JSX runtime: `automatic` or `classic`
`importSource`	Source for JSX imports (default: `react`)

Advanced Options

Option	Type	Description
`sourceMaps`	`boolean`	Enable source maps
`stats`	`boolean`	Enable build statistics output
`nodePolyfill`	`boolean`	Polyfill Node.js built-ins for browser
`persistentCaching`	`boolean`	Enable persistent build cache
`pluginRuntimeStrategy`	`string`	Plugin execution: `workerThreads` or `childProcesses`

Programmatic API

build()


const { build } = require('@utoo/pack');
 
await build({
  config: {
    mode: "production",
    entry: [{ import: "./src/index.ts" }],
    output: { path: "./dist" }
  }
});

serve()


const { serve } = require('@utoo/pack');
 
await serve(bundleOptions, projectPath, rootPath, {
  logServerInfo: true,
  port: 3000
});

defineConfig()


// utoopack.config.mjs
import { defineConfig } from '@utoo/pack';
 
export default defineConfig({
  entry: [{ import: './src/index.ts' }],
  output: { path: './dist', clean: true },
});

For the full configuration schema, see config_schema.json .