# Installation Guide

This guide covers installation and setup for all supported frameworks.

## Prerequisites

- Node.js 16+ or 18+ (LTS recommended)
- npm 7+ or yarn 1.22+ or pnpm 7+
- Modern browser with WebRTC support (Chrome 90+, Firefox 88+, Safari 15+, Edge 90+)

## Package Overview

The `@networkoptix/crdt-sync` library is organized into framework-specific modules:

- `@networkoptix/crdt-sync/core` - Core CRDT models and providers
- `@networkoptix/crdt-sync/react` - React hooks and utilities
- `@networkoptix/crdt-sync/angular` - Angular signals and services
- `@networkoptix/crdt-sync/vue` - Vue composables
- `@networkoptix/crdt-sync/vanilla` - Vanilla JavaScript / Web Components

## React Installation

### npm

```bash
# Install the library
npm install @networkoptix/crdt-sync

# Install peer dependencies
npm install mobx mobx-react-lite yjs

# Optional: Install WebRTC/WebSocket providers
npm install y-webrtc y-websocket
```

### yarn

```bash
yarn add @networkoptix/crdt-sync
yarn add mobx mobx-react-lite yjs
yarn add y-webrtc y-websocket
```

### pnpm

```bash
pnpm add @networkoptix/crdt-sync
pnpm add mobx mobx-react-lite yjs
pnpm add y-webrtc y-websocket
```

### Verify Installation

```typescript
// src/App.tsx
import { useSyncModel } from '@networkoptix/crdt-sync/react';
import { createSingletonModel } from '@networkoptix/crdt-sync/core';

console.log('✅ CRDT-sync installed successfully');
```

## Angular Installation

### npm

```bash
# Install the library
npm install @networkoptix/crdt-sync

# Install peer dependencies
npm install mobx mobx-keystone yjs

# Optional: Install providers
npm install y-webrtc y-websocket
```

### Angular Version Compatibility

| Angular Version | @networkoptix/crdt-sync | Status |
|-----------------|-------------------------|--------|
| 17+ | Latest | ✅ Recommended |
| 16 | Latest | ✅ Supported |
| 15 | Latest | ✅ Supported |
| 14 | Latest | ⚠️ Not tested |

### TypeScript Configuration

Add to `tsconfig.json`:

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

### Verify Installation

```typescript
// app.component.ts
import { createSyncSignal } from '@networkoptix/crdt-sync/angular';
import { createSingletonModel } from '@networkoptix/crdt-sync/core';

console.log('✅ CRDT-sync installed successfully');
```

## Vue Installation

### npm

```bash
# Install the library
npm install @networkoptix/crdt-sync

# Install peer dependencies
npm install mobx yjs

# Optional: Install providers
npm install y-webrtc y-websocket
```

### Vue Version Compatibility

| Vue Version | @networkoptix/crdt-sync | Status |
|-------------|-------------------------|--------|
| 3.3+ | Latest | ✅ Recommended |
| 3.2 | Latest | ✅ Supported |
| 3.0-3.1 | Latest | ⚠️ Limited testing |
| 2.x | Not supported | ❌ Use Vue 3 |

### Vite Configuration

If using Vite, no additional configuration needed. For older setups:

```javascript
// vite.config.js
export default {
  optimizeDeps: {
    include: ['mobx', 'yjs']
  }
};
```

### Verify Installation

```vue
<script setup>
import { useSyncModelSync } from '@networkoptix/crdt-sync/vue';
import { createSingletonModel } from '@networkoptix/crdt-sync/core';

console.log('✅ CRDT-sync installed successfully');
</script>
```

## Vanilla JavaScript / Web Components

### npm

```bash
npm install @networkoptix/crdt-sync
npm install mobx yjs
npm install y-webrtc y-websocket
```

### Browser / CDN

```html
<!-- Using unpkg CDN -->
<script src="https://unpkg.com/mobx@6/dist/mobx.umd.production.min.js"></script>
<script src="https://unpkg.com/yjs@13/dist/yjs.js"></script>
<script src="https://unpkg.com/@networkoptix/crdt-sync@latest/dist/vanilla.umd.js"></script>

<script>
  const { BaseSyncElement, createSingletonModel } = window.CrdtSync;
  console.log('✅ CRDT-sync loaded from CDN');
</script>
```

### TypeScript Support

```bash
# TypeScript definitions included
npm install @types/node --save-dev
```

### Verify Installation

```javascript
// main.js
import { BaseSyncElement } from '@networkoptix/crdt-sync/vanilla';
import { createSingletonModel } from '@networkoptix/crdt-sync/core';

console.log('✅ CRDT-sync installed successfully');
```

## Common Installation Issues

### Issue: Peer Dependency Warnings

```
npm WARN @networkoptix/crdt-sync@1.0.0 requires a peer of mobx@^6.0.0 but none is installed.
```

**Solution**: Install the missing peer dependency:
```bash
npm install mobx@^6.0.0
```

### Issue: Module Not Found

```
Error: Cannot find module '@networkoptix/crdt-sync/react'
```

**Solution**: Ensure you're importing from the correct subpath:
```typescript
// ✅ Correct
import { useSyncModel } from '@networkoptix/crdt-sync/react';

// ❌ Wrong
import { useSyncModel } from '@networkoptix/crdt-sync';
```

### Issue: TypeScript Errors

```
TS2307: Cannot find module '@networkoptix/crdt-sync/react' or its corresponding type declarations.
```

**Solution**: Update `tsconfig.json`:
```json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

### Issue: Build Errors with Vite

```
Error: Failed to resolve entry for package "@networkoptix/crdt-sync"
```

**Solution**: Add to `vite.config.js`:
```javascript
export default {
  resolve: {
    alias: {
      '@networkoptix/crdt-sync': '@networkoptix/crdt-sync'
    }
  }
};
```

### Issue: WebRTC Connection Failures

```
Error: WebRTC connection failed
```

**Solution**: Configure signaling server:
```typescript
const model = new MyModel({
  provider: {
    webrtc: {
      signaling: ['wss://your-signaling-server.com'],
      iceServers: [
        { urls: 'stun:stun.l.google.com:19302' }
      ]
    }
  }
});
```

## Next Steps

After installation:

1. ✅ **[Quick Start Tutorial](./quick-start.md)** - Build your first sync app in 15 minutes
2. ✅ **[Core Concepts](./core-concepts.md)** - Understand CRDTs, Yjs, and MobX integration

## Optional Dependencies

### Production Deployment

For production deployments, consider:

```bash
# Signaling server for WebRTC
npm install y-websocket-server

# TURN server for NAT traversal
# (Use external service like Twilio, Coturn, or self-host)
```

### Development Tools

```bash
# TypeScript types
npm install --save-dev @types/yjs
```

## Troubleshooting

If you encounter issues:

1. Check [Common Issues](../troubleshooting/common-issues.md)
2. Verify peer dependencies: `npm ls mobx yjs`
3. Clear cache: `npm cache clean --force`
4. Reinstall: `rm -rf node_modules package-lock.json && npm install`

## Support

- 📖 [Documentation](https://crdt-sync.networkoptix.com)
- 🐛 [Report Issues](https://github.com/networkoptix/crdt-sync/issues)
- 💬 [Discussions](https://github.com/networkoptix/crdt-sync/discussions)
