### Install and Run Development Server

Source: https://github.com/utooland/utoo/blob/next/examples/with-postcss/README.md

Install dependencies and start the development server to observe CSS transformations.

```bash
npm install
npm run dev
```

--------------------------------

### Start Development Server

Source: https://github.com/utooland/utoo/blob/next/CONTRIBUTING.md

Start the development server, primarily used for @utoo/web and example projects.

```bash
npm run dev
```

--------------------------------

### Run Utoo Web Demo

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/README.md

Start the web demo for @utoo/web. This command launches the demo application, typically for testing and examples.

```bash
npm start -w utooweb-demo
```

--------------------------------

### Install @utoo/web

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/README.md

Install the @utoo/web package using npm.

```bash
npm install @utoo/web
```

--------------------------------

### Install @utoo/pack-cli

Source: https://github.com/utooland/utoo/blob/next/packages/pack-cli/README.md

Install the pack-cli as a development dependency.

```bash
ut install @utoo/pack-cli --save-dev
```

--------------------------------

### Start Demo Application

Source: https://github.com/utooland/utoo/blob/next/AGENTS.md

Start the 'utooweb-demo' application. This command is part of the demo workflow for the web package.

```bash
ut start --workspace utooweb-demo
```

--------------------------------

### Initial Installation State

Source: https://github.com/utooland/utoo/blob/next/e2e/pm/arborist/testing-peer-dep-conflict-chain/override/readme.md

Illustrates the dependency tree after the initial installation of gatsby and its related packages.

```text
+-- root
    +-- gatsby
    +-- @pmmmwh/react-refresh-webpack-plugin
    +-- react-refresh@0.7.2
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/utooland/utoo/blob/next/CONTRIBUTING.md

Install all project dependencies using npm after cloning the repository.

```bash
npm install
```

--------------------------------

### Install and Run UtooWeb Demo

Source: https://github.com/utooland/utoo/blob/next/examples/utooweb-demo/README.md

Follow these commands to set up the utooweb-demo project. Ensure you are in the correct directory before executing.

```sh
cd ../../packages/utoo-web
npm install
npm run install-toolchain
npm run dev # or npm run build
cd ../../examples/utooweb-demo
npm run start
```

--------------------------------

### Install @utoo/pack-shared

Source: https://github.com/utooland/utoo/blob/next/packages/pack-shared/README.md

Install the shared utilities package using npm.

```bash
npm install @utoo/pack-shared
```

--------------------------------

### Install wasm-bindgen-cli

Source: https://github.com/utooland/utoo/blob/next/CONTRIBUTING.md

Install the wasm-bindgen-cli tool, required for building the web version of Utoo.

```bash
cargo install wasm-bindgen-cli@0.2.106
```

--------------------------------

### Install Utoo Package Manager and Bundler

Source: https://context7.com/utooland/utoo/llms.txt

Choose one method for global package manager installation. Install the bundler and CLI as development dependencies in your project.

```bash
# Install package manager globally (pick one)
brew install utooland/tap/utoo     # macOS / Linux via Homebrew

```

```bash
npm install -g utoo                # cross-platform via npm

```

```bash
cargo install utoo-pm              # build from source via Cargo

```

```bash
# Install bundler and CLI into a project
ut install @utoo/pack --save-dev

```

```bash
ut install @utoo/pack-cli --save-dev   # optional – provides the `up` binary

```

```bash
# Install browser-compatible version
ut install @utoo/web --save

```

--------------------------------

### Start Development Server

Source: https://github.com/utooland/utoo/blob/next/packages/pack-cli/README.md

Launch the development server with Hot Module Replacement (HMR) enabled.

```bash
utx up dev
```

--------------------------------

### Install @utoo/pack

Source: https://github.com/utooland/utoo/blob/next/packages/pack/README.md

Install the @utoo/pack package as a development dependency.

```bash
ut install @utoo/pack --save-dev
```

--------------------------------

### Install cargo-nextest

Source: https://github.com/utooland/utoo/blob/next/crates/pack-tests/README.md

Install the cargo-nextest tool to enable advanced testing features.

```bash
cargo install cargo-nextest
```

--------------------------------

### Install Utoo Core Toolchain

Source: https://github.com/utooland/utoo/blob/next/README.md

Choose one installation method for the core Utoo toolchain. This includes the package manager and bundler CLI.

```bash
# Install the core toolchain (pick one)
brew install utooland/tap/utoo   # macOS / Linux via Homebrew

```

```bash
npm install -g utoo              # cross-platform via npm

```

```bash
cargo install utoo-pm            # build from source via Cargo

```

--------------------------------

### Install Project Dependencies

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Resolves dependencies from package.json and installs them. Alternatively, a package-lock.json string can be passed directly to install().

```typescript
const packageLock = await project.deps();
await project.install(packageLock);
```

--------------------------------

### Starting State Dependency Tree

Source: https://github.com/utooland/utoo/blob/next/e2e/pm/arborist/sequental-peer-dep-tree-shuffling/README.md

Illustrates the dependency tree when 'root' only depends on 'a'.

```text
root
+-- a
+-- b@1
```

--------------------------------

### Configure @utoo/pack

Source: https://github.com/utooland/utoo/blob/next/packages/pack-cli/README.md

Set up the utoopack.json configuration file in your project's root directory. This example shows entry points and output settings.

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

--------------------------------

### Resolve and Install Dependencies

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Resolves dependencies from `package.json` and installs them. An existing `package-lock.json` string can also be passed directly to `install()`.

```APIDOC
## `project.deps()` and `project.install(packageLockJsonString)`

### Description

Resolves dependencies from `package.json` and installs them. Alternatively, pass an existing `package-lock.json` string directly to `install()`.

### Usage

```typescript
const packageLock = await project.deps();
await project.install(packageLock);
```

### See Also

* [`project.deps()`](#projectdepsoptions)
* [`project.install(packageLockJsonString, maxConcurrentDownloads)`](#projectinstallpackagelockjsonstring-maxconcurrentdownloads)
```

--------------------------------

### Install @utoo/pack-cli Bundler CLI

Source: https://github.com/utooland/utoo/blob/next/README.md

Optionally, install the command-line interface for the bundler to easily manage development and build processes.

```bash
# Install the bundler cli in nodejs environment(Optional)
ut install @utoo/pack-cli --save-dev

```

--------------------------------

### Start Development Mode with Inline Configuration and Callback

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Starts development mode with file watching and HMR, using an inline configuration and providing a callback for build completion events. This allows for automatic updates and custom post-build actions.

```typescript
project.dev({
  config: {
    entry: [{ import: "./src/index.tsx", name: "main" }],
    output: { path: "dist" },
  },
  onUpdate: (result) => {
    console.log('Build completed', result.issues);
  },
});
```

--------------------------------

### Install @utoo/pack Bundler

Source: https://github.com/utooland/utoo/blob/next/README.md

Install the next-gen bundler powered by Turbopack into your project as a development dependency.

```bash
# Install the bundler in nodejs environment
ut install @utoo/pack --save-dev

```

--------------------------------

### Run Hono Dev Server

Source: https://github.com/utooland/utoo/blob/next/examples/with-proxy/README.md

Commands to start the Hono development server for the 'with-proxy' workspace.

```bash
# From repo root
ut start --workspace with-proxy
# or
npx up --workspace with-proxy
```

--------------------------------

### Install Rust Toolchain for Utoo

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/README.md

Install the necessary Rust toolchain for building Utoo projects. This command ensures the correct Rust version is available.

```bash
npm run install-toolchain
```

--------------------------------

### Install @utoo/web

Source: https://github.com/utooland/utoo/blob/next/README.md

Install the web-compatible version of the Utoo toolchain, which can run in the browser via WASM.

```bash
# Install the web version
ut install @utoo/web --save

```

--------------------------------

### Install Dependencies

Source: https://context7.com/utooland/utoo/llms.txt

Install npm dependencies using a lockfile JSON. Options include specifying the registry and controlling concurrency and omitted package types.

```typescript
// 4. Install dependencies (returns a package-lock JSON string)
const lockfileJson = await project.deps({ registry: "https://registry.npmjs.org" });
await project.install(lockfileJson, { maxConcurrentDownloads: 8, omit: ["dev"] });
```

--------------------------------

### Install Service Worker for Preview

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Register and install the service worker to enable the preview functionality. This is a required step for the preview feature to work.

```typescript
await project.installServiceWorker();
```

--------------------------------

### Utoo Bundler CLI (`up dev`) Commands

Source: https://context7.com/utooland/utoo/llms.txt

The `up dev` command starts the development server. It can be configured with project paths, webpack compatibility, and tracing options.

```bash
# Start dev server (reads utoopack.json or utoopack.config.mjs from cwd)
up dev

```

```bash
# Specify a custom project directory
up dev --project ./my-app

```

```bash
# Specify both project and monorepo root
up dev --project ./packages/ui --root .

```

```bash
# Enable webpack compatibility mode (reads webpack.config.js)
up dev --webpack

```

```bash
# Disable default tracing logs
up dev --no-tracing

```

--------------------------------

### Parallelism Loss Calculation Example

Source: https://github.com/utooland/utoo/blob/next/agents/reports/utoopack_performance_report_20260121_130000.md

This example demonstrates the calculation of lost parallelism by comparing theoretical maximum throughput with actual thread work. It quantifies the performance bottleneck in milliseconds.

```text
Theoretical Max Throughput = 33 threads × 3,060.7ms = 101,003 ms
Actual Thread Work         = 55,223.7 ms
Lost Parallelism           = 101,003 - 55,223.7 = 45,779 ms (45.3%)
```

--------------------------------

### Build Project with Configuration

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Builds the project using a provided configuration object. Loaders can be added to devDependencies and installed.

```typescript
await project.build({
  config: {
    entry: [{ import: "./src/index.tsx", name: "main" }],
    output: { path: "dist" },
    stats: true,
  },
});
```

--------------------------------

### Start Development Mode with Callback

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Starts development mode with file watching and HMR, providing a callback function that receives build results. This is useful for integrating custom logic after each incremental build.

```typescript
project.dev({
  onUpdate: (result) => {
    console.log('Build completed', result.issues);
  },
});
```

--------------------------------

### Programmatic Development Server (`serve()` function)

Source: https://context7.com/utooland/utoo/llms.txt

Start a Hono-based HTTP/WebSocket development server with HMR support using the `@utoo/pack` library. The server automatically finds a free port if the requested one is in use.

```typescript
// dev.mjs
import { serve } from "@utoo/pack";
import path from "node:path";
import { fileURLToPath } from "node:url";

const projectPath = path.dirname(fileURLToPath(import.meta.url));

await serve(
  {
    config: {
      entry: [{ import: "./src/index.ts", html: { template: "./index.html" } }],
      output: { path: "./dist", clean: true },
      sourceMaps: true,
      optimization: { minify: false },
      devServer: {
        port: 3000,
        hot: true,
        proxy: [{ context: ["/api"], target: "http://localhost:8080", changeOrigin: true }]
      },
    },
  },
  projectPath,
  undefined,
  {
    port: 3000,
    hostname: "localhost",
    https: false,
    logServerInfo: true,
    onReady: ({ port, hostname }) => {
      console.log(`Dev server ready at http://${hostname}:${port}`);
    },
  },
);

```

--------------------------------

### Dependency Cycle Example

Source: https://github.com/utooland/utoo/blob/next/e2e/pm/arborist/pathological-dep-nesting-cycle/README.md

Illustrates a pathological dependency cycle where packages A and B depend on each other recursively. This can lead to infinite nesting.

```text
a@1 -> b@1
a@2 -> b@2
b@1 -> a@2
b@2 -> a@1
```

--------------------------------

### project.readFile and project.writeFile

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API_zh-CN.md

Reads from and writes to project files. readFile is used to get file content for display, and writeFile is used to save changes back to the file system, typically with debouncing.

```APIDOC
## project.readFile(filePath, encoding?)

### Description
Reads the content of a file from the project.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (JavaScript function call)

### Endpoint
None

### Parameters
* `filePath` (string): The path to the file to read.
* `encoding` (string, optional): The encoding to use when reading the file (e.g., "utf8").

### Request Example
```typescript
const content = await project.readFile(filePath, "utf8");
```

### Response
* `content` (string): The content of the file.

### Response Example
None

## project.writeFile(filePath, content)

### Description
Writes content to a file in the project.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (JavaScript function call)

### Endpoint
None

### Parameters
* `filePath` (string): The path to the file to write to.
* `content` (string | Buffer): The content to write to the file.

### Request Example
```typescript
await project.writeFile(selectedFilePath, newContent);
```

### Response
None

### Response Example
None
```

--------------------------------

### Development Server with HMR using @utoo/pack

Source: https://github.com/utooland/utoo/blob/next/packages/pack/README.md

Start a development server with Hot Module Replacement (HMR) enabled. The config object should specify entry points, output details, and source map settings.

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

// 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
    }
  });
}
```

--------------------------------

### Build Project

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Initiates the project build process. Configuration can be provided directly or via a `utoopack.json` file.

```APIDOC
## `project.build(options)` and `project.dev(options)`

### Description

Builds the project. Pass a config object directly, or write a `utoopack.json` to the project root.

### Usage Example

```typescript
await project.build({
  config: {
    entry: [{ import: "./src/index.tsx", name: "main" }],
    output: { path: "dist" },
    stats: true,
  },
});
```

### See Also

* [`project.build(options)`](#projectbuildoptions)
* [`project.dev(options)`](#projectdevoptions)

### Loaders

To use loaders, add them to `devDependencies` in your `package.json` along with `loader-runner`, then install them. See [`loadersImportMap`](#new-utooprojectoptions) for an alternative that avoids file system I/O overhead.
```

--------------------------------

### Build for Production

Source: https://github.com/utooland/utoo/blob/next/packages/pack-cli/README.md

Generate a production-ready build of your project.

```bash
utx up build
```

--------------------------------

### project.install()

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Populates the `node_modules` directory based on a provided lock file string. This is used after dependencies have been resolved.

```APIDOC
## project.install(packageLockJsonString, maxConcurrentDownloads?)

### Description
Populates the `node_modules` directory based on a lock file string.

### Parameters
#### Path Parameters
- **packageLockJsonString** (string) - Required - A JSON string of the dependency lock file (from `deps()` or a `package-lock.json` file).
- **maxConcurrentDownloads** (number, optional) - Optional - Maximum concurrent package downloads.

### Returns
`Promise<void>`
```

--------------------------------

### Install typos-cli

Source: https://github.com/utooland/utoo/blob/next/CONTRIBUTING.md

Install the typos-cli spell checker for code and documentation. It is used in the pre-push git hook.

```bash
cargo install typos-cli --locked
```

--------------------------------

### Build All Packages

Source: https://github.com/utooland/utoo/blob/next/CONTRIBUTING.md

Build all packages and crates in the monorepo using npm or Turborepo.

```bash
npm run build
```

```bash
npx turbo run build
```

--------------------------------

### Build Project Using Default Configuration

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Triggers the build process using the default configuration defined in `utoopack.json`. This is the standard way to initiate a production build.

```typescript
await project.build();
```

--------------------------------

### Initialize Utoo Project

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Creates a new Utoo project instance. Requires specifying the current working directory and URLs for worker threads.

```APIDOC
## `new UtooProject(options)`

Creates a new project instance.

### Description

Initializes a new Utoo project with the specified configuration.

### Parameters

#### Options

* `cwd` (string) - Required - The absolute path that will serve as the root of the project in the real file system (e.g., `/my-app`).
* `workerUrl` (string) - Required - URL or inline data URI for the Worker thread where the `Project` instance's core logic actually runs. The `Project` object you interact with in the main thread is a proxy that delegates all core tasks (like file system operations) to this Worker. Import the pre-bundled inline version: `import workerUrl from "@utoo/web/esm/workerInline"`.
* `threadWorkerUrl` (string) - Required - URL or inline data URI for a separate Worker thread dedicated to handling CPU-intensive tasks like bundling and compiling. Import: `import threadWorkerUrl from "@utoo/web/esm/threadWorkerInline"`.
* `loaderWorkerUrl` (string, optional) - URL or inline data URI for a separate Worker thread dedicated to handling webpack loaders. Import: `import loaderWorkerUrl from "@utoo/web/esm/loaderWorkerInline"`.
* `wasmUrl` (string, optional) - URL to the WASM binary. When using inline workers, this must be set explicitly since Blob URL workers cannot auto-resolve the WASM path. Use `new URL("@utoo/web/esm/utoo/index_bg.wasm", import.meta.url).href` to let your bundler handle it.
* `serviceWorker` (object, optional)
  * `url` (string) - Required - The URL to the service worker script.
  * `scope` (string) - Required - The URL scope that the service worker will intercept requests for. This is the base path for your preview environment.
* `loadersImportMap` (object, optional) - A map for configuring Webpack loader imports. This is an optional advanced configuration. Typically, you can simply declare loader dependencies in `package.json` to install and use them. Configuring `loadersImportMap` allows you to provide pre-bundled, single files that adhere to the CommonJS specification (as a URL string or content string). This avoids file system I/O overhead caused by `require` operations during loader execution, thereby significantly improving build performance. The key is the loader's name, and the value is the URL or content string of the UMD/CommonJS module. Loaders will be executed in parallel in a web worker pool.
```

--------------------------------

### Install LLVM on macOS

Source: https://github.com/utooland/utoo/blob/next/CONTRIBUTING.md

Install LLVM using Homebrew on macOS, which is required to build utoo-wasm on macOS for @utoo/web. This ensures the build uses clang from Homebrew.

```bash
brew install llvm
```

```bash
export PATH="$(brew --prefix llvm)/bin:$PATH"
export CC="$(brew --prefix llvm)/bin/clang"
export AR="$(brew --prefix llvm)/bin/llvm-ar"
```

--------------------------------

### Instantiate and Mount Project in Browser

Source: https://context7.com/utooland/utoo/llms.txt

Instantiate the Project class and wait for its WASM worker to mount. Ensure correct URLs for worker and WASM files are provided.

```typescript
import { Project } from "@utoo/web";

// 1. Instantiate (spins up a WASM Web Worker)
const project = new Project({
  cwd: "/workspace",                    // virtual FS root
  workerUrl: new URL("./esm/workerInline.js", import.meta.url).href,
  threadWorkerUrl: new URL("./esm/threadWorkerInline.js", import.meta.url).href,
  wasmUrl: new URL("./esm/utoo/index_bg.wasm", import.meta.url).href,
  serviceWorker: {
    url: "/serviceWorkerBundle.js",
    scope: "/",
    targetDirToCwd: "dist",           // serve dist/ at scope root
  },
});

// 2. Wait for worker to mount
await project.mount();
```

--------------------------------

### Build All Packages

Source: https://github.com/utooland/utoo/blob/next/AGENTS.md

Build all packages within the monorepo using Turborepo.

```bash
npm run build
```

--------------------------------

### project.installServiceWorker()

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Registers and activates the service worker defined in the constructor, which is essential for the preview functionality.

```APIDOC
## project.installServiceWorker()

### Description
Registers and activates the service worker defined in the constructor. This is essential for the preview functionality.

### Returns
`Promise<void>`
```

--------------------------------

### Instantiate Project with @utoo/web

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Create a Project instance with configuration for workers and the service worker. Worker scripts are pre-bundled as inline base64 data URIs.

```typescript
import { Project as UtooProject } from "@utoo/web";
import workerUrl from "@utoo/web/esm/workerInline";
import threadWorkerUrl from "@utoo/web/esm/threadWorkerInline";
import loaderWorkerUrl from "@utoo/web/esm/loaderWorkerInline";

const project = new UtooProject({
    // Project root directory in the file system.
    cwd: "/utooweb-demo",

    // Inline worker data URI for file system and core functionality.
    workerUrl,

    // Inline worker data URI for heavy tasks.
    threadWorkerUrl,
    
    // Inline worker data URI for webpack loaders.
    loaderWorkerUrl,

    // URL to the WASM binary. Use `new URL()` to let your bundler handle it.
    wasmUrl: new URL("@utoo/web/esm/utoo/index_bg.wasm", import.meta.url).href,

    // Preview service worker configuration.
    serviceWorker: {
        url: `${location.origin}/serviceWorker.js`,
        scope: "/preview", // Path controlled by the service worker.
    },
    // ImportMap for running webpack loaders
    loadersImportMap: {
      // accept an umd script url or a script content string
      "xyzLoader": "https://x.y.z.js"
    }
});
```

--------------------------------

### project.updateInfoSubscribe()

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Subscribes to compilation lifecycle events, providing a modern way to handle build start and end notifications.

```APIDOC
## project.updateInfoSubscribe(aggregationMs, callback)

### Description
Subscribe to compilation lifecycle events. This replaces the old `onUpdateStart` and `onUpdateEnd` hooks.

### Parameters
#### Path Parameters
- **aggregationMs** (number) - Required - Aggregation time in milliseconds.
- **callback** (function) - Required - Receives an `UpdateMessage` object.

### Example
```typescript
project.updateInfoSubscribe(100, (message) => {
  if (message.updateType === "start") {
    console.log('Build starting...');
  } else if (message.updateType === "end") {
    const { duration, tasks } = message.value;
    console.log(`Build completed in ${duration}ms with ${tasks} tasks`);
  }
});
```
```

--------------------------------

### Console Log Output

Source: https://github.com/utooland/utoo/blob/next/examples/externals/index.html

Logs messages to the console to indicate test environment setup completion and script loading status.

```javascript
console.log('Test environment setup complete');
// Check console for output
console.log('All scripts loaded');
```

--------------------------------

### Subscribe to Build Lifecycle Events

Source: https://context7.com/utooland/utoo/llms.txt

Subscribe to notifications about the build process lifecycle, such as start and end events. A throttle interval can be specified.

```typescript
// 9. Subscribe to build lifecycle events (start / end)
project.updateInfoSubscribe(100, (msg) => console.log("Build status:", msg));
```

--------------------------------

### Build Utoopack NAPI Bindings

Source: https://github.com/utooland/utoo/blob/next/agents/utoopack-performance-agent.md

Build the NAPI bindings for Utoopack before profiling. This is a prerequisite for performance analysis.

```bash
npm run build:local -w @utoo/pack
```

--------------------------------

### Initial Dependency Graph

Source: https://github.com/utooland/utoo/blob/next/e2e/pm/arborist/sequental-peer-dep-tree-shuffling/README.md

Defines the initial dependency relationships between packages.

```text
root -> a
root' -> (a, c)
a -> b@1
c -> PEER b@2
```

--------------------------------

### project.build

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API_zh-CN.md

Initiates the project build process. This method is called when a user triggers a build, and it handles the compilation and bundling of project assets.

```APIDOC
## project.build()

### Description
Initiates the project build process.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (JavaScript function call)

### Endpoint
None

### Parameters
None

### Request Example
```typescript
setIsBuilding(true);
try {
  await project.build();
    // 构建成功
} catch (e) {
    // 构建失败
} finally {
    setIsBuilding(false);
}
```

### Response
None

### Response Example
None
```

--------------------------------

### Configure Custom Loaders with `module.rules`

Source: https://context7.com/utooland/utoo/llms.txt

Apply Turbopack-compatible loaders or pass through webpack-style loaders using glob-keyed rules. Ensure the loader is installed and configured correctly.

```typescript
// utoopack.config.mjs
import { defineConfig } from "@utoo/pack";

export default defineConfig({
  entry: [{ import: "./src/index.ts" }],
  module: {
    rules: {
      "*.mdx": [{ loader: "@mdx-js/loader", options: { providerImportSource: "@mdx-js/react" } }],
      "*.svg": { loaders: [{ loader: "@svgr/webpack", options: { icon: true } }], as: "*.js" },
      "*.txt": { type: "raw" },
    },
  },
  output: { path: "./dist", clean: true },
});
```

--------------------------------

### Enable Development Mode with HMR

Source: https://context7.com/utooland/utoo/llms.txt

Start a development server with file watching and hot module replacement. A callback function can be provided to handle rebuild completion.

```typescript
// 6. Dev mode with file watching + HMR
await project.dev({
  config: {
    entry: [{ import: "./src/index.tsx", html: { template: "./index.html" } }],
    output: { path: "./dist" },
  },
  onUpdate: (result) => console.log("Rebuild complete, issues:", result.issues),
});
```

--------------------------------

### project.dev()

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Starts development mode with file watching and Hot Module Replacement (HMR). This function continuously watches for file changes and automatically triggers incremental builds.

```APIDOC
## project.dev(options?)

### Description
Starts development mode with file watching and Hot Module Replacement (HMR). Unlike `build()`, `dev()` continuously watches for file changes and automatically triggers incremental builds.

### Parameters
#### Query Parameters
- **config** (`ConfigComplete`, optional): The bundler configuration object. When provided, the `utoopack.json` file is not read from disk.
- **onUpdate** (function, optional): Callback when a build completes, receives the build result (including issues and diagnostics).

### Example
```typescript
// Dev mode with callback
project.dev({
  onUpdate: (result) => {
    console.log('Build completed', result.issues);
  },
});

// Dev mode with inline config
project.dev({
  config: {
    entry: [{ import: "./src/index.tsx", name: "main" }],
    output: { path: "dist" },
  },
  onUpdate: (result) => {
    console.log('Build completed', result.issues);
  },
});
```
```

--------------------------------

### Utoo Pack JSON Configuration (`utoopack.json`)

Source: https://context7.com/utooland/utoo/llms.txt

Configure project settings, entry points, output, resolution, definitions, optimization, and styles.

```json
{
  "$schema": "./node_modules/@utoo/pack/config_schema.json",
  "entry": [
    {
      "import": "./src/index.ts",
      "html": {
        "template": "./index.html",
        "title": "My App",
        "inject": "body",
        "scriptLoading": "defer"
      }
    }
  ],
  "output": {
    "path": "./dist",
    "filename": "[name].[contenthash:6].js",
    "chunkFilename": "[name].[contenthash:8].js",
    "cssFilename": "[name].[contenthash:6].css",
    "clean": true
  },
  "resolve": {
    "alias": { "@utils": "./src/utils" }
  },
  "define": {
    "API_URL": "\"https://api.example.com\""
  },
  "optimization": {
    "minify": true,
    "moduleIds": "deterministic",
    "splitChunks": {
      "js": { "minChunkSize": 2000, "maxChunkCountPerGroup": 1, "maxMergeChunkSize": 20000 }
    }
  },
  "styles": {
    "autoCssModules": true,
    "emotion": true,
    "styledJsx": true
  }
}
```

--------------------------------

### Command Line Build with Webpack Config

Source: https://context7.com/utooland/utoo/llms.txt

Build a project using an existing `webpack.config.js` file via the Utoo CLI.

```bash
# Build using existing webpack.config.js
up build --webpack

# Dev server using webpack.config.js
up dev --webpack

```

--------------------------------

### Trigger Build Process with Inline Configuration

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Triggers the build process using an inline configuration object, bypassing the `utoopack.json` file. Useful for dynamic build setups.

```typescript
await project.build({
  config: {
    entry: [{ import: "./src/index.tsx", name: "main" }],
    output: { path: "dist" },
  },
});
```

--------------------------------

### Subscribe to Compilation Lifecycle Events

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Subscribes to compilation lifecycle events, providing callbacks for build start and end. This method allows for granular control and monitoring of the build process.

```typescript
project.updateInfoSubscribe(100, (message) => {
  if (message.updateType === "start") {
    console.log('Build starting...');
  } else if (message.updateType === "end") {
    const { duration, tasks } = message.value;
    console.log(`Build completed in ${duration}ms with ${tasks} tasks`);
  }
});
```

--------------------------------

### Configure Proxy Rules with proxyFromObject

Source: https://github.com/utooland/utoo/blob/next/examples/with-proxy/README.md

Example of using `proxyFromObject` to dynamically build proxy rules from a JavaScript object in a configuration file. This is useful for managing complex proxy configurations.

```typescript
import { proxyFromObject } from "@utoo/pack-shared";

export default {
  devServer: {
    proxy: [
      ...proxyFromObject({
        "/api": "http://localhost:3000",
        "/auth": { target: "http://localhost:5000", changeOrigin: true },
      }),
    ],
  },
};
```

--------------------------------

### TypeScript Import Error Example

Source: https://github.com/utooland/utoo/blob/next/crates/pack-tests/tests/snapshot/basic/alias/issues/Export-notFound-doesn-t-exist-in-target-module-942f39.txt

Illustrates an import statement that causes a 'Export notFound doesn't exist in target module' error. This occurs when trying to import an identifier that is not exported by the specified module.

```typescript
import style from '@/index.less';
import { a } from '@/a?query';
import { output } from '../../../output';
import { runtime } from 'smallfish:runtime';
import { notFound } from './x';

notFound;

runtime;
```

--------------------------------

### project.build

Source: https://github.com/utooland/utoo/blob/next/packages/utoo-web/API.md

Initiates the project build process. This command triggers Turbopack to perform incremental builds and generate necessary assets.

```APIDOC
## `project.build()`

### Description
Builds the project. This command triggers Turbopack to perform incremental builds.

### Example
```typescript
setIsBuilding(true);
try {
    await project.build();
    // Build succeeded
} catch (e) {
    // Build failed
} finally {
    setIsBuilding(false);
}
```
```

--------------------------------

### Less Import Error Example

Source: https://github.com/utooland/utoo/blob/next/crates/pack-tests/tests/snapshot/style/less/issues/Module-not-found-Can-t-resolve-mixins-~antd-reset.-e006b9.txt

Illustrates a 'Module not found' error in Less when trying to import a mixin from Ant Design. The error occurs because the resolver interprets 'mixins/~antd/reset.css' as a module named 'mixins' with a subpath.

```less
@import 'mixins/~antd/reset.css';
```

```less
@import '~antd/reset.css';
```

```less
@import 'antd/reset2.css';
```

```less
body {
  background-color: black;
}
```