API Reference

`new UtooProject(options)`

Creates a new project instance.

Options

Option	Type	Description
`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 of the Worker thread where the `Project` instance’s core logic runs. The main thread `Project` object is a proxy that delegates tasks to this Worker.
`threadWorkerUrl`	string	Required. URL of a separate Worker thread for CPU-intensive tasks like bundling and compiling.
`loaderWorkerUrl`	string	URL of a separate Worker thread for handling webpack loaders.
`wasmUrl`	string	URL to the WASM binary. Defaults to the bundled binary.
`serviceWorker`	object	Service worker configuration for preview functionality. See sub-options below.
`logFilter`	string	Filter string for tracing logs.
`loadersImportMap`	object	A map for configuring Webpack loader imports. Keys are loader names, values are UMD/CommonJS module URLs or content strings.

serviceWorker sub-options:

Option	Type	Description
`url`	string	Required. The URL to the service worker script.
`scope`	string	Required. The URL scope that the service worker will intercept requests for.
`targetDirToCwd`	string	Path from the target directory to the project root.

File System Methods

These methods are asynchronous and mimic the Node.js fs API.

project.writeFile(path, content, encoding?)

Writes content to a file in the real file system. If the file doesn’t exist, it will be created.

Parameter	Type	Description
`path`	string	The absolute path to the file (e.g., `/src/index.js`).
`content`	string \| Uint8Array	The content to write.
`encoding`	string	The encoding (e.g., `'utf8'`). Optional.

project.readFile(path, encoding?)

Reads the content of a file.

Parameter	Type	Description
`path`	string	The path to the file.
`encoding`	string	The encoding of the file (e.g., `'utf8'`). If not provided, returns `Uint8Array`.

Returns: Promise<string> (with encoding) or Promise<Uint8Array> (without encoding).

project.readdir(path, options?)

Reads the contents of a directory.

Parameter	Type	Description
`path`	string	The path to the directory.
`options.recursive`	boolean	If `true`, reads recursively.

Returns: Promise<Dirent[]> — An array of Dirent objects with name, isDirectory(), and isFile() methods.

project.mkdir(path, options?)

Creates a new directory.

Parameter	Type	Description
`path`	string	The path to the directory to be created.
`options.recursive`	boolean	If `true`, creates parent directories as needed.

project.rm(path, options?)

Removes a file or directory.

Parameter	Type	Description
`path`	string	The path to the file or directory to be removed.
`options.recursive`	boolean	If `true`, performs a recursive directory removal.

project.rmdir(path, options?)

Removes a directory.

Parameter	Type	Description
`path`	string	The path to the directory to be removed.
`options.recursive`	boolean	If `true`, removes recursively.

project.copyFile(src, dst)

Copies a file from source to destination.

Parameter	Type	Description
`src`	string	Source file path.
`dst`	string	Destination file path.

project.stat(path)

Gets file/directory stats.

Parameter	Type	Description
`path`	string	The path to the file or directory.

Returns: Promise<Stats> — Stats object with size, isDirectory(), isFile(), timestamps (atime, mtime, ctime, birthtime), etc.

Dependency Management

project.deps(options?)

Resolves dependencies from the project’s package.json and generates a lock file string. This enables dependency resolution directly in the browser without requiring a pre-existing package-lock.json.

Option	Type	Description
`registry`	string	The npm registry URL. Default: `https://registry.npmmirror.com`
`concurrency`	number	Maximum concurrent network requests. Default: `20`

Returns: Promise<string> — A JSON string representing the resolved dependency lock file, compatible with package-lock.json format.

Examples:

app.ts


// Using default registry (npmmirror)
const lockFile = await project.deps();
 
// Using official npm registry
const lockFile = await project.deps({
    registry: "https://registry.npmjs.org"
});
 
// Using a private registry with custom concurrency
const lockFile = await project.deps({
    registry: "https://npm.mycompany.com",
    concurrency: 10
});

project.install(packageLockJsonString, options?)

Populates the node_modules directory based on a lock file string.

Parameter	Type	Description
`packageLockJsonString`	string	A JSON string of the dependency lock file (from `deps()` or a `package-lock.json` file).
`options.maxConcurrentDownloads`	number	Maximum concurrent package downloads.
`options.omit`	string[]	Dependency types to omit. Possible values: `"dev"`, `"optional"`.

Examples:

app.ts


// Basic install
await project.install(lockFile);
 
// Install with concurrency limit
await project.install(lockFile, { maxConcurrentDownloads: 10 });
 
// Install without dev dependencies (production mode)
await project.install(lockFile, { omit: ["dev"] });

Build & Development

project.build()

Triggers the build process in the thread worker. It reads the build configuration from utoopack.json in the project’s root and runs the bundler based on that configuration.

Returns: Promise<BuildOutput> — Object with an issues array containing any build warnings or errors.

app.ts


const result = await project.build();
if (result.issues.length > 0) {
  console.warn("Build completed with issues:", result.issues);
}

project.dev(onUpdate?)

Start dev mode with file watching. Triggers incremental rebuilds on file changes.

Parameter	Type	Description
`onUpdate`	function	Callback called on each rebuild with `BuildOutput`. Optional.

app.ts


project.dev((result) => {
  console.log("Rebuild complete, issues:", result.issues);
});

project.hmrSubscribe(identifier, callback)

Subscribe to HMR (Hot Module Replacement) events for a specific identifier.

Parameter	Type	Description
`identifier`	string	The module identifier to subscribe to.
`callback`	function	Called with update instructions when the module changes.

project.updateInfoSubscribe(aggregationMs, callback)

Subscribe to compilation lifecycle events (start/end).

Parameter	Type	Description
`aggregationMs`	number	Aggregation interval in milliseconds.
`callback`	function	Called with `UpdateMessage` on compilation events.

Preview Functionality

project.installServiceWorker()

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

Types

BuildOutput


interface BuildOutput {
  issues: Issue[];
}

InstallOptions


interface InstallOptions {
  maxConcurrentDownloads?: number;
  omit?: ("dev" | "optional")[];
}

DepsOptions


interface DepsOptions {
  registry?: string;
  concurrency?: number;
}

Dirent


class Dirent {
  name: string;
  isDirectory(): boolean;
  isFile(): boolean;
}

Stats


class Stats {
  size: number;
  isDirectory(): boolean;
  isFile(): boolean;
  atime: Date;
  mtime: Date;
  ctime: Date;
  birthtime: Date;
}