Developer Setup

This guide covers cloning the monorepo, installing dependencies, and running the development workflow.

Prerequisites

Tool	Required Version	Check
Node.js	>= 20.0.0	node --version
pnpm	>= 9.0.0	pnpm --version
Git	Any recent version	git --version

The monorepo uses pnpm@9.15.0 as its package manager (declared in package.json via the packageManager field).

TIP

If you don't have pnpm installed, enable it via Node.js corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Clone and Install

git clone https://github.com/web-engine-dev/monorepo.git
cd monorepo
pnpm install

pnpm install reads the workspace configuration from pnpm-workspace.yaml and links all 92+ packages together. This takes a few minutes on first run.

Build All Packages

pnpm build

This uses Turborepo to build packages in dependency order. Each package builds to ESM + CJS with TypeScript declaration files via tsup.

To build only packages affected by your changes (relative to origin/main):

pnpm build:affected

Run Tests

pnpm test

This runs all package tests via Turborepo. Tests use Vitest with globals: false (explicit imports required).

To test only affected packages:

pnpm test:affected

To run tests for a single package:

cd packages/core/ecs
pnpm test

To run a specific test file:

cd packages/core/ecs
vitest run src/World.test.ts

Type-Check

pnpm typecheck

Runs tsc --noEmit across all packages. The project uses TypeScript strict mode with noUncheckedIndexedAccess enabled.

Lint

pnpm lint

Runs ESLint across all packages using the flat config format (eslint.config.mjs).

Watch Mode

For active development, run the watch mode for all packages:

pnpm dev

Or for a single package:

cd packages/core/ecs
pnpm dev

Running the Playground

The playground is a Vite-based interactive demo environment:

pnpm --filter playground dev

This starts a dev server (typically at http://localhost:5173) with hot reload for all demo files.

Running the Editor

The editor has a frontend (SolidJS) and a backend server. Run them in separate terminals:

# Terminal 1: Editor server
pnpm --filter @web-engine-dev/editor-server dev

# Terminal 2: Editor frontend
pnpm --filter @web-engine-dev/editor dev

IDE Setup

VS Code (Recommended)

The monorepo works well with VS Code. Recommended extensions:

• ESLint -- Provides inline lint feedback
• TypeScript -- Use the workspace version (select "Use Workspace Version" when prompted)
• Vitest -- Run tests from the editor sidebar

Useful settings.json entries for this project:

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "editor.formatOnSave": false,
  "eslint.useFlatConfig": true
}

Other Editors

Any editor with TypeScript language server support works. Ensure it is configured to:

• Use the workspace TypeScript version (5.5+)
• Respect the tsconfig.json in each package directory
• Support ESLint flat config if providing inline lint

Project Structure at a Glance

monorepo/
├── packages/             # 92+ engine packages (core, systems, rendering, ...)
├── apps/
│   ├── playground/       # Interactive demo environment
│   ├── editor/           # Visual editor (SolidJS)
│   ├── editor-server/    # Editor backend (Node.js)
│   ├── docs/             # Documentation site (VitePress)
│   ├── server/           # Game server
│   ├── examples/         # Example applications
│   └── benchmarks/       # Performance benchmarks
├── shared/               # Shared build and test configurations
├── testing/              # Integration and E2E test infrastructure
├── tools/                # Build tools and scripts
├── pnpm-workspace.yaml   # Workspace package definitions
└── turbo.json            # Turborepo pipeline configuration

Shared Configurations

Build and test configurations are centralized in the shared/ directory:

File	Purpose
tsup.config.ts	ESM + CJS output, dts generation, ES2022 target, treeshaking
vitest.config.ts	Node environment, v8 coverage, globals: false
tsconfig.package.json	Extends tsconfig.base.json, strict mode, noUncheckedIndexedAccess

Each package extends these shared configs in its own tsup.config.ts, vitest.config.ts, and tsconfig.json.

Versioning

The monorepo uses Changesets for version management:

pnpm changeset

This prompts you to select affected packages, choose a semver bump level, and write a description. Changesets are committed alongside code and processed on release.