Installation

Prerequisites

Before installing, make sure you have:

• Node.js >= 20.0.0
• pnpm >= 9.0.0 (recommended package manager)

You can install pnpm globally if you don't have it:

npm install -g pnpm

Installing from npm

Web Engine Dev follows a modular "Bring Your Own Engine" philosophy. You can install individual packages or the full engine umbrella package.

Individual Packages

Install only the packages you need for minimal bundle size:

# Core ECS
pnpm add @web-engine-dev/ecs

# Math library
pnpm add @web-engine-dev/math

# Renderer (WebGPU)
pnpm add @web-engine-dev/renderer

# Pick and choose what you need
pnpm add @web-engine-dev/input @web-engine-dev/audio @web-engine-dev/physics2d

This is recommended for production projects where you want fine control over bundle size and dependencies.

Engine Meta-Package

For quick prototyping or small games, install the umbrella package that re-exports everything:

pnpm add @web-engine-dev/engine

The engine package exposes all modules as namespaces to avoid naming conflicts:

import { ECS, Math, Renderer, Input, Audio } from '@web-engine-dev/engine';

const world = ECS.createWorld();
const vec = Math.vec3(1, 2, 3);

It also provides the Engine class, plugins, and presets for common game types:

import {
  createEngine,
  Game2DPreset,
  Game2DPlugins,
  RenderPlugin,
  InputPlugin,
} from '@web-engine-dev/engine';

When to use which

• Individual packages -- Large projects, production builds, when bundle size matters
• Engine meta-package -- Prototyping, game jams, small projects, learning the API

Building from Source

To work with the engine source code or contribute:

# Clone the repository
git clone https://github.com/web-engine-dev/monorepo.git
cd monorepo

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run all tests
pnpm test

Monorepo Commands

Command	Description
pnpm build	Build all packages (uses Turborepo)
pnpm dev	Watch mode for all packages
pnpm test	Run all tests
pnpm lint	Lint all packages
pnpm typecheck	Type-check all packages
pnpm build:affected	Build only changed packages
pnpm test:affected	Test only changed packages

TypeScript Configuration

Web Engine Dev is built with strict TypeScript. Your project should use compatible settings.

The minimum recommended tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "lib": ["ES2022", "DOM", "DOM.Iterable"]
  }
}

Key settings:

• target: "ES2022" -- All packages compile to ES2022
• moduleResolution: "bundler" -- Required for correct module resolution with bundlers like Vite
• verbatimModuleSyntax: true -- Use import type { Foo } for type-only imports
• noUncheckedIndexedAccess: true -- Prevents unchecked array/object index access (enforced in the engine)

Browser Requirements

The renderer uses a WebGPU runtime backend:

Backend	Status	Browser Support
WebGPU	Required	Chrome 113+, Edge 113+, Firefox (behind flag), Safari 18+

If WebGPU is unavailable, renderer device creation fails with an explicit error.

Next Steps

• Quick Start -- Build your first ECS application in 5 minutes
• Project Setup -- Set up a complete project with Vite
• First Game -- Build a simple game step by step