Environment:Mlc ai Web llm Node Build Toolchain

Knowledge Sources	mlc-ai/web-llm TypeScript Rollup
Domains	Infrastructure, Build_System
Last Updated	2026-02-14 22:00 GMT

Overview

Node.js build environment with TypeScript 4.9+, Rollup bundler, and Jest test runner for compiling and testing the WebLLM library.

Description

This environment defines the build-time requirements for developing, compiling, and testing the WebLLM library. It is not a runtime environment (runtime is the browser); instead it specifies the toolchain needed to build the npm package from TypeScript source. The build system uses Rollup for bundling, TypeScript for compilation targeting ES6, and Jest for unit testing. The TypeScript configuration includes DOM, WebWorker, and ES2022 library types along with WebGPU type definitions.

Usage

Use this environment when building WebLLM from source, running tests, or developing examples. This is required for contributors and developers who need to compile the library rather than consuming the published npm package.

System Requirements

Category	Requirement	Notes
Runtime	Node.js	Required for npm, build tools, and test runner
Package Manager	npm	Uses `package-lock.json` for deterministic installs
OS	Linux, macOS, or Windows	Standard Node.js development environment
Disk	Minimal (~200 MB)	For node_modules and build output

Dependencies

System Packages

Node.js (LTS recommended)
npm

Build Dependencies

`typescript` >= 4.9.5
`rollup` >= 4.53.3
`rollup-plugin-typescript2` >= 0.36.0
`@rollup/plugin-commonjs` >= 29.0.0
`@rollup/plugin-node-resolve` >= 16.0.3
`tslib` >= 2.3.1

Type Definitions

`@webgpu/types` >= 0.1.24 (WebGPU API types)
`@types/chrome` >= 0.0.266 (Chrome Extension API types)
`@types/serviceworker` >= 0.0.86 (Service Worker API types)

Test Dependencies

`jest` >= 30.2.0
`ts-jest` >= 29.4.5
`@types/jest` >= 30.0.0

Lint Dependencies

`eslint` >= 9.39.1
`prettier` = 3.6.2
`husky` >= 9.0.11 (Git hooks)

Credentials

No credentials required for building. Model weights are not needed at build time.

Quick Install

# Clone and install dependencies
git clone https://github.com/mlc-ai/web-llm.git
cd web-llm
npm install

# Build the library
npm run build

# Run tests
npm test

# Lint
npm run lint

Code Evidence

TypeScript configuration from `tsconfig.json:1-16`:

{
  "compilerOptions": {
    "target": "es6",
    "lib": ["dom", "WebWorker", "es2022"],
    "moduleResolution": "Node",
    "strict": true,
    "typeRoots": [
      "./node_modules/@webgpu/types",
      "./node_modules/@types"
    ]
  }
}

Build and test scripts from `package.json:8-14`:

{
  "scripts": {
    "build": "rollup -c && ./cleanup-index-js.sh",
    "lint": "npx eslint ./src/ ./tests/ ./examples/ && npx prettier ./src/ ./tests/ ./examples/ --check",
    "test": "jest --coverage",
    "format": "prettier --write \"./src/\" \"./examples/\" \"./tests/\"",
    "prepare": "husky"
  }
}

Common Errors

Error Message	Cause	Solution
TypeScript compilation errors about WebGPU types	Missing `@webgpu/types` package	Run `npm install` to install all devDependencies
`Cannot find module '@mlc-ai/web-runtime'`	Dev dependency not installed	Run `npm install`; this is a devDependency
Jest test failures about `TextEncoder`	Node.js version too old	Use Node.js 18+ which includes `TextEncoder` globally

Compatibility Notes

Build output: The library compiles to ES6 modules in `lib/` directory.
TypeScript target: ES6 with ES2022 lib (uses modern JS features like `Promise.allSettled`, `globalThis`).
Module system: ES modules (`"type": "module"` in package.json).
This is build-time only: The built library runs in browsers, not Node.js.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment