{"id":16731696,"url":"https://github.com/spearwolf/shadow-objects","last_synced_at":"2026-05-17T01:38:13.668Z","repository":{"id":249034825,"uuid":"830432277","full_name":"spearwolf/shadow-objects","owner":"spearwolf","description":"A view-decoupled component framework for games and other complex in-browser applications.","archived":false,"fork":false,"pushed_at":"2025-03-13T10:01:39.000Z","size":2752,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-13T11:20:00.752Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spearwolf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-18T09:04:44.000Z","updated_at":"2025-03-13T10:01:43.000Z","dependencies_parsed_at":"2024-07-18T12:57:28.854Z","dependency_job_id":"768dd066-ff1d-4574-add0-3eb960d65991","html_url":"https://github.com/spearwolf/shadow-objects","commit_stats":null,"previous_names":["spearwolf/shadow-objects"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spearwolf%2Fshadow-objects","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spearwolf%2Fshadow-objects/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spearwolf%2Fshadow-objects/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spearwolf%2Fshadow-objects/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spearwolf","download_url":"https://codeload.github.com/spearwolf/shadow-objects/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243772729,"owners_count":20345705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T23:38:35.199Z","updated_at":"2026-05-17T01:38:13.663Z","avatar_url":"https://github.com/spearwolf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shadow-objects\n\nA reactive Entity-Component Framework for running app logic in a shadow environment.\n\n\u003e [!WARNING]\n\u003e This is a highly experimental framework that is slowly maturing. Use at your own risk.\n\n---\n\n## The Mental Model: ECS for Web Apps\n\nThink of shadow-objects like a **game engine for your application state**:\n\n- **Your UI (React, Vue, Svelte, Canvas)** is the renderer — it just draws what it's told.\n- **Entities** are lightweight game objects in the shadow environment. No logic, just identity.\n- **Shadow Objects** are ECS components that attach behavior to entities — signals, effects, event handlers.\n- **The Kernel** runs the show: it manages entity lifecycle and schedules updates.\n\nYour UI is the renderer. Shadow Objects is the game world.\n\nThe shadow environment can run on the **main thread** (local mode, zero overhead) or in a **web worker** (remote mode, parallel execution). Both are first-class citizens.\n\n**Shadow Objects doesn't replace React, Vue, or Svelte.** It's the logic layer those frameworks render. When your app state gets complex enough that you're fighting your UI framework's reactivity, shadow-objects gives you a clean separation: business logic over here, rendering over there.\n\nIf Redux and Zustand are global state on one thread, shadow-objects is reactive ECS state across any number of threads.\n\n---\n\n\u003e [!WARNING]\n\u003e 🚀 This is a highly experimental framework that is slowly maturing. Use at your own risk. 🔥\n\n---\n\n## Documentation\n\n**The complete and authoritative documentation is in [`packages/shadow-objects/docs/`](packages/shadow-objects/docs/).**\n\n| File | What's inside |\n| :--- | :--- |\n| [**getting-started.md**](packages/shadow-objects/docs/getting-started.md) | Hello World, your first shadow object |\n| [**concepts.md**](packages/shadow-objects/docs/concepts.md) | ECS mental model, architecture, lifecycle, entity tree |\n| [**guides.md**](packages/shadow-objects/docs/guides.md) | Writing shadow objects, view integration, multi-env setup |\n| [**api-reference.md**](packages/shadow-objects/docs/api-reference.md) | Full API reference |\n| [**cheat-sheet.md**](packages/shadow-objects/docs/cheat-sheet.md) | At-a-glance tables and snippets |\n| [**best-practices.md**](packages/shadow-objects/docs/best-practices.md) | Patterns, composition, cleanup, testing |\n\n---\n\n## Project Structure (Monorepo)\n\nThis repository is a monorepo managed with [nx](https://nx.dev/) and [pnpm](https://pnpm.io/).\n\n| Package | npm name | Description |\n| :--- | :--- | :--- |\n| [**`shadow-objects`**](packages/shadow-objects/) | `@spearwolf/shadow-objects` | The core framework library |\n| [**`shae-offscreen-canvas`**](packages/shae-offscreen-canvas/) | `@spearwolf/shae-offscreen-canvas` | Custom element for offscreen canvas rendering — demonstrates shadow-objects for graphics |\n| [**`shadow-objects-testing`**](packages/shadow-objects-testing/) | — (not published) | Functional and integration tests |\n| [**`shadow-objects-e2e`**](packages/shadow-objects-e2e/) | — (not published) | End-to-end tests using [Playwright](https://playwright.dev/) |\n\n---\n\n## Available Scripts\n\nRun these commands from the root directory:\n\n| Command | Description |\n| :--- | :--- |\n| `pnpm cbt` | **Clean, Build, Test.** Runs a full cycle: clean, build, and test the entire workspace. |\n| `pnpm start` | Starts the **shae-offscreen-canvas** demo server. |\n| `pnpm test` | Runs all tests (Unit, Integration, E2E) across all packages. |\n| `pnpm test:ci` | Runs tests excluding E2E (faster, for CI pipelines). |\n| `pnpm build` | Builds all packages. |\n| `pnpm lint` | Runs linter across the entire workspace. |\n| `pnpm clean` | Deletes all build artifacts (`dist`, `build` folders). |\n\n---\n\n## Development Setup\n\n1. **Prerequisites:** Node.js \u003e=20.12.2, pnpm \u003e=9.1.2\n2. **Install Dependencies:**\n    ```sh\n    pnpm install\n    ```\n3. **Install Playwright Browsers (for E2E Tests):**\n    ```sh\n    cd packages/shadow-objects-e2e\n    pnpm exec playwright install chromium firefox\n    cd ../..\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspearwolf%2Fshadow-objects","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspearwolf%2Fshadow-objects","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspearwolf%2Fshadow-objects/lists"}