Configuration

@utoo/pack can be configured with utoopack.json, utoopack.config.mjs, or the Node 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
  }
}

Use utoopack.json when your config is fully JSON-serializable. Use utoopack.config.* when you want type inference or JS-based composition. The config-file form can also carry runtime-only UserConfig fields such as processEnv, watch, dev, buildId, tracing, projectPath, and rootPath.

Top-level Options

Option	Description
`mode`	Build mode: `development` or `production`
`target`	Target environment
`entry`	Entry points, HTML generation, and library output
`output`	Output path, filename templates, public path, asset copying
`resolve`	Aliases and extension resolution
`define`	Build-time constant replacement
`provider`	Auto-provide modules, similar to Webpack `ProvidePlugin`
`externals`	Keep dependencies out of the bundle
`module`	Custom module rules and loaders
`styles`	CSS Modules, Less, Sass, PostCSS, Emotion, styled-components, styled-jsx
`images`	Asset inlining behavior
`react`	JSX runtime and React transform options
`optimization`	Minification, tree shaking, split chunks, import transforms
`devServer`	Host, port, HTTPS, HMR, proxy
`sourceMaps`	Enable source maps
`stats`	Emit build stats
`persistentCaching`	Reuse cache across runs
`nodePolyfill`	Polyfill Node.js built-ins for browser builds
`experimental`	Experimental flags exposed by the package

Core Configuration

mode and target

Build mode affects optimizations and defaults. target selects the output runtime.


{
  "mode": "production",
  "target": "browser"
}

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

entry

Define application entry points, HTML generation, and library output.


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

output

Configure output path, file naming, static copying, and runtime asset URLs.


{
  "output": {
    "path": "./dist",
    "type": "standalone",
    "filename": "[name].[contenthash:8].js",
    "chunkFilename": "[name].[contenthash:8].js",
    "cssFilename": "[name].[contenthash:8].css",
    "cssChunkFilename": "[name].[contenthash:8].css",
    "assetModuleFilename": "assets/[name].[contenthash:8][ext]",
    "publicPath": "/",
    "crossOriginLoading": "anonymous",
    "copy": ["./public"],
    "chunkLoadingGlobal": "TURBOPACK",
    "clean": true,
    "entryRootExport": "AppExports"
  }
}

Option	Description
`path`	Output directory
`type`	Output type: `standalone` or `export`
`filename`	Entry chunk filename template
`chunkFilename`	Non-entry chunk filename template
`cssFilename`	Main CSS filename template
`cssChunkFilename`	CSS chunk filename template
`assetModuleFilename`	Asset filename template
`publicPath`	Public URL path for assets
`crossOriginLoading`	Cross-origin attribute for lazy chunks
`copy`	Copy static files into the output directory
`chunkLoadingGlobal`	Global variable used by the runtime to load chunks
`clean`	Clean output directory before build
`entryRootExport`	Expose entry exports on `window` / `globalThis`

define

Build-time variable replacement.


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

provider

Automatically inject modules, similar to Webpack ProvidePlugin.


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

externals

Exclude dependencies from the bundle.


{
  "externals": {
    "react": "React",
    "react-dom": "ReactDOM",
    "lodash-es": {
      "root": "_",
      "type": "global"
    }
  }
}

Externals support simple string globals, script/commonjs/esm/global forms, and more advanced subpath configuration.

resolve

Configure module resolution. resolve.alias rewrites an import request to another module or path, using Turbopack-style alias rules .


{
  "resolve": {
    "alias": {
      "react": "preact/compat",
      "@/*": "./src/*",
      "legacy/": "./src/legacy/",
      "runtime/*": ["./src/runtime/*", "./fallback/runtime/*"]
    },
    "extensions": [".ts", ".tsx", ".js", ".jsx"]
  }
}

resolve.alias accepts this shape:


type ResolveAlias =
  Record<string, string | string[] | Record<string, string | string[]>>

Matching rules:

Alias	Matches	Does not match
`"foo": "./src/foo"`	`import "foo"`	`import "foo/bar"`
`"foo/": "./src/foo/"`	`import "foo/bar"` and deeper subpaths	`import "foo"`
`"foo/": "./src/foo/"`	Same as `"foo/": "./src/foo/"`	`import "foo"`

Use * when you want to carry the matched subpath into the replacement. The * can match across path separators, so "@/*": "./src/*" resolves imports such as @/components/Button.

Alias values can be:

Value	Behavior
`string`	Rewrite to a single package or path
`string[]`	Try multiple candidates in order
condition object	Pick a value by condition, commonly `browser`, with `default` as the fallback

Relative path values are resolved from the project root, for example "./src/foo". Absolute paths inside the project are normalized to project-relative paths. Avoid aliases that point outside the project directory.

utoopack.config.mjs


import { defineConfig } from '@utoo/pack';
 
export default defineConfig({
  resolve: {
    alias: {
      // Exact replacement
      lodash: 'lodash-es',
 
      // Subpath replacement
      '@/*': './src/*',
 
      // Directory shortcut
      'components/': './src/components/',
 
      // Multiple candidates
      'runtime/*': ['./src/runtime/*', './fallback/runtime/*'],
 
      // Conditional alias
      env: {
        browser: './src/env.browser.ts',
        default: './src/env.node.ts',
      },
    },
    extensions: ['.ts', '.tsx', '.js', '.jsx'],
  },
});

Migrating from Webpack alias

The biggest difference is subpath matching. In Webpack, an alias such as foo: path.resolve(__dirname, 'src/foo') is commonly used to cover both foo and foo/bar. In Utoopack, a plain key is exact. Add /* or use the trailing slash shortcut when you want subpath imports.

Webpack	Utoopack
`foo: path.resolve(__dirname, 'src/foo')` for `import "foo"`	`"foo": "./src/foo"`
`foo: path.resolve(__dirname, 'src/foo')` for `import "foo/bar"`	`"foo/": "./src/foo/"` or `"foo/": "./src/foo/"`
`'@': path.resolve(__dirname, 'src')` for `import "@/Button"`	`"@/": "./src/"`
`react: 'preact/compat'`	`"react": "preact/compat"`

Webpack’s $ suffix marks an exact alias, for example foo$: './src/foo'. Utoopack does not need that suffix because exact matching is the default:


{
  "resolve": {
    "alias": {
      "foo": "./src/foo"
    }
  }
}

This only affects:


import "foo"

It does not affect:


import "foo/bar"

To cover subpaths, use:


{
  "resolve": {
    "alias": {
      "foo/*": "./src/foo/*"
    }
  }
}

Or the directory shortcut:


{
  "resolve": {
    "alias": {
      "foo/": "./src/foo/"
    }
  }
}

module

Define loader-based module rules. Rule objects can include loaders, condition, and type.


{
  "module": {
    "rules": {
      "*.md": ["raw-loader"],
      "*.svg": [
        {
          "loaders": [
            {
              "loader": "@svgr/webpack",
              "options": {
                "icon": true
              }
            }
          ]
        }
      ]
    }
  }
}

styles

Configure built-in style processing.


{
  "styles": {
    "autoCssModules": true,
    "postcss": {},
    "less": {
      "implementation": "less"
    },
    "sass": {
      "implementation": "sass"
    },
    "inlineCss": {
      "injectType": "styleTag"
    },
    "emotion": {
      "autoLabel": "dev-only"
    },
    "styledComponents": {
      "displayName": true,
      "ssr": true
    },
    "styledJsx": {
      "useLightningcss": true
    }
  }
}

images

Configure image inlining.


{
  "images": {
    "inlineLimit": 8192
  }
}

react

React transform options.


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

optimization


{
  "optimization": {
    "minify": true,
    "treeShaking": true,
    "moduleIds": "deterministic",
    "splitChunks": {
      "js": {
        "minChunkSize": 50000,
        "maxChunkCountPerGroup": 40,
        "maxMergeChunkSize": 200000
      }
    },
    "modularizeImports": {
      "lodash": {
        "transform": "lodash/{{member}}",
        "preventFullImport": true
      }
    },
    "packageImports": ["lodash-es"],
    "transpilePackages": ["shared-ui"],
    "removeConsole": {
      "exclude": ["error"]
    },
    "concatenateModules": true,
    "removeUnusedExports": true,
    "removeUnusedImports": true
  }
}

Common optimization fields exposed by the current package also include compress, noMangling, nestedAsyncChunking, and wasmAsAsset.

devServer

The local repo currently supports hot, host, port, https, and proxy here.


{
  "devServer": {
    "hot": true,
    "host": "0.0.0.0",
    "port": 3000,
    "https": false,
    "proxy": [
      {
        "context": ["/api"],
        "target": "http://localhost:7001",
        "changeOrigin": true,
        "pathRewrite": {
          "^/api": ""
        }
      }
    ]
  }
}

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
`experimental`	`object`	Experimental package options

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({
  config: {
    mode: "development",
    entry: [{ import: "./src/index.ts" }],
    output: { path: "./dist" },
    devServer: { port: 3000, hot: true }
  }
});

defineConfig()


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 .