shadow-objects

A reactive entity←component framework that feels home in the shadows 🧛

Warning

🚀 This is a highly experimental framework that is slowly maturing. Use at your own risk. 🔥

Documentation 📚

The complete and authoritative documentation is located in the packages/shadow-objects/docs/ directory.

• Fundamentals: Understand the mental model, architecture, and lifecycle.
• Guides: Step-by-step instructions.
• API Reference: Detailed API docs.

🏗️ Project Structure

This repository is a monorepo managed with nx and pnpm.

Package	Description
shadow-objects	The core framework library.
shae-offscreen-canvas	A custom HTML element implementing an offscreen canvas.
shadow-objects-testing	Functional and integration tests.
shadow-objects-e2e	End-to-end tests using Playwright.

⚡ Available Scripts

Run these commands from the root directory:

Command	Description
pnpm cbt	Clean, Build, Test. Runs a full clean build and test cycle for the entire workspace.
pnpm start	Starts the shae-offscreen-canvas demo server.
pnpm test	Runs all tests (Unit, Integration, E2E) across all packages.
pnpm test:ci	Runs tests excluding E2E (faster, for CI pipelines).
pnpm build	Builds all packages.
pnpm lint	Runs linting across the workspace.
pnpm clean	Cleans all build artifacts (dist, build folders).

⚙️ Development Setup

1. Prerequisites: Node.js >=20.12.2, pnpm >=9.1.2
2. Install dependencies:

   pnpm install

3. Install Playwright browsers (for E2E):

   cd packages/shadow-objects-e2e
   pnpm exec playwright install chromium firefox
   cd ../..