@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/guides/installation.md

@@ -1,323 +0,0 @@
-# Installation
-
-This guide covers installing XMachines packages in your project across different package managers and environments.
-
-## Prerequisites
-
-Before installing XMachines, ensure you have:
-
-- **Node.js 22+** (or compatible runtime)
-- **Package manager**: npm, pnpm, or yarn
-- **TypeScript** (optional but recommended for full type safety)
-
-## Installing XMachines
-
-Choose your preferred package manager:
-
-### npm
-
-```bash
-npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
-```
-
-### pnpm
-
-```bash
-pnpm add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
-```
-
-### yarn
-
-```bash
-yarn add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
-```
-
-## Package Selection Guide
-
-XMachines consists of 8 modular packages. Choose the packages based on your needs:
-
-### Core Packages (Required)
-
-**@xmachines/play**
-
-- Foundation package with core protocols and contracts
-- Required by all other packages
-
-**@xmachines/play-actor**
-
-- Abstract actor base class extending XState Actor
-- Required for instantiating state machines
-
-**@xmachines/play-signals**
-
-- TC39 Signals polyfill for reactive updates
-- Required for reactive state observation
-
-**@xmachines/play-xstate**
-
-- XState v5 logic adapter with catalog binding
-- Required for state machine definitions
-
-**Minimal installation:**
-
-```bash
-npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
-```
-
-### UI and Routing (Optional)
-
-**@xmachines/play-ui**
-
-- UI schema protocol with Zod validation
-- Install if: Building declarative UI structures from state
-
-**@xmachines/play-router**
-
-- Route tree protocol and machine crawler
-- Install if: Implementing logic-driven routing
-
-**@xmachines/play-tanstack-react-router**
-
-- TanStack Router adapter with signal observation
-- Install if: Using TanStack Router for navigation
-
-**@xmachines/play-react**
-
-- React view renderer with JSON-Render
-- Install if: Building React applications
-
-**@xmachines/play-catalog**
-
-- State machine catalog and registry patterns
-- Install if: Managing multiple machines with type inference
-
-### Complete Installation
-
-For full-featured development with React and routing:
-
-```bash
-npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/play-ui @xmachines/play-router @xmachines/play-tanstack-react-router @xmachines/play-react @xmachines/play-catalog
-```
-
-**See also:** [Package Overview](/docs/api/guides/package-overview) for detailed descriptions of each package.
-
-## Environment-Specific Setup
-
-### Browser (Vite, Webpack, or other bundlers)
-
-No special configuration needed. ESM imports work out of the box:
-
-```typescript
-import { createMachine } from "@xmachines/play-xstate";
-import { createActor } from "@xmachines/play-actor";
-import { signal } from "@xmachines/play-signals";
-```
-
-Most modern bundlers (Vite, Webpack 5+, Rollup) handle ESM packages automatically.
-
-### Node.js
-
-XMachines uses ESM (ECMAScript Modules) exclusively. Ensure your project is configured for ESM:
-
-**Option 1: Set `"type": "module"` in package.json**
-
-```json
-{
-	"type": "module",
-	"dependencies": {
-		"@xmachines/play": "^1.0.0"
-	}
-}
-```
-
-**Option 2: Use `.mjs` file extensions**
-
-Alternatively, name your files with `.mjs` extension:
-
-```bash
-node my-app.mjs
-```
-
-**Import example:**
-
-```typescript
-import { createMachine } from "@xmachines/play-xstate";
-import { createActor } from "@xmachines/play-actor";
-
-const machine = createMachine({
-	id: "example",
-	initial: "idle",
-	states: {
-		idle: { on: { START: "running" } },
-		running: { on: { STOP: "idle" } },
-	},
-});
-
-const actor = createActor(machine);
-actor.start();
-```
-
-### Deno
-
-XMachines works with Deno via npm specifiers:
-
-```typescript
-import { createMachine } from "npm:@xmachines/play-xstate";
-import { createActor } from "npm:@xmachines/play-actor";
-import { signal } from "npm:@xmachines/play-signals";
-```
-
-Alternatively, use a CDN like esm.sh:
-
-```typescript
-import { createMachine } from "https://esm.sh/@xmachines/play-xstate";
-```
-
-### TypeScript
-
-XMachines is written in TypeScript and includes built-in type definitions. No separate `@types` package is needed.
-
-**Recommended tsconfig.json settings:**
-
-```json
-{
-	"compilerOptions": {
-		"target": "ESNext",
-		"module": "ESNext",
-		"moduleResolution": "bundler",
-		"strict": true,
-		"esModuleInterop": true,
-		"skipLibCheck": false,
-		"resolveJsonModule": true
-	}
-}
-```
-
-**Key settings:**
-
-- **`moduleResolution: "bundler"`** (recommended) or `"node16"` for Node.js projects
-- **`strict: true`** enables full type checking
-- **`target: "ESNext"`** leverages modern JavaScript features
-
-**Type inference:**
-
-XMachines provides full type inference from machine catalog through to components:
-
-```typescript
-import { createMachine } from "@xmachines/play-xstate";
-
-const machine = createMachine({
-	id: "typed",
-	initial: "idle",
-	context: { count: 0 },
-	states: {
-		idle: { on: { START: "running" } },
-		running: { on: { STOP: "idle" } },
-	},
-});
-
-// TypeScript infers exact state types
-type States = typeof machine.states; // "idle" | "running"
-```
-
-## Verifying Installation
-
-Test your installation with this simple script:
-
-**test.ts** (or test.js with `"type": "module"`):
-
-```typescript
-import { createMachine } from "@xmachines/play-xstate";
-import { createActor } from "@xmachines/play-actor";
-
-const machine = createMachine({
-	id: "test",
-	initial: "ready",
-	states: {
-		ready: {},
-	},
-});
-
-const actor = createActor(machine);
-actor.start();
-
-console.log("✓ XMachines installed successfully");
-console.log("Current state:", actor.getSnapshot().value);
-```
-
-**Run the test:**
-
-```bash
-# TypeScript (requires tsx or ts-node)
-npx tsx test.ts
-
-# Or compile first
-npx tsc test.ts && node test.js
-
-# JavaScript (with "type": "module")
-node test.js
-```
-
-**Expected output:**
-
-```
-✓ XMachines installed successfully
-Current state: ready
-```
-
-## Troubleshooting
-
-### Module Not Found
-
-**Error:** `Cannot find module '@xmachines/play-xstate'`
-
-**Solutions:**
-
-- Verify package is installed: `npm list @xmachines/play-xstate`
-- Re-install dependencies: `npm install`
-- Check `node_modules/@xmachines/` directory exists
-
-### ESM Import Errors
-
-**Error:** `SyntaxError: Cannot use import statement outside a module`
-
-**Solutions:**
-
-- Add `"type": "module"` to package.json
-- Or rename files to `.mjs` extension
-- Or use dynamic import: `const { createMachine } = await import('@xmachines/play-xstate')`
-
-### Type Errors
-
-**Error:** `Could not find a declaration file for module '@xmachines/play-xstate'`
-
-**Solutions:**
-
-- Types are built-in; no `@types` package needed
-- Check TypeScript version (4.5+ required)
-- Verify `moduleResolution` in tsconfig.json is set correctly
-- Try `npm install` again to ensure types are properly linked
-
-### Version Mismatches
-
-**Error:** Type incompatibilities between packages
-
-**Solution:**
-Install all XMachines packages with matching major versions:
-
-```bash
-npm install @xmachines/play@latest @xmachines/play-xstate@latest @xmachines/play-actor@latest @xmachines/play-signals@latest
-```
-
-## Next Steps
-
-Now that XMachines is installed, you're ready to build your first state machine:
-
-- **[Getting Started →](getting-started.md)** - Build your first state machine
-- **[Core Concepts](/docs/api/guides/core-concepts)** - Understand the architecture
-- **[Package Overview](/docs/api/guides/package-overview)** - Deep dive into each package
-- **[Examples](/examples)** - See XMachines in action
-
----
-
-**Need help?** Check the [Architecture Documentation](/architecture) or [API Reference](/docs/api) for detailed information.