# Local Development

Develop and test TelemetryOS applications locally before deployment using the TelemetryOS CLI development server.

# Local Development

Develop and test TelemetryOS applications locally before deployment.

## Overview

The TelemetryOS CLI provides a local development server that simulates the platform environment, allowing you to build and test applications without deploying to the cloud.

## CLI Tool

### Installation

```bash
npm install -g @telemetryos/cli
```

Or use locally in your project:

```bash
npm install --save-dev @telemetryos/cli
```

### Available Commands

#### tos init

Scaffold a new application from template.

```bash
tos init my-application
```

**What it does:**

* Creates project directory
* Sets up Vite + React + TypeScript template
* Creates `telemetry.config.json`
* Installs dependencies
* Initializes git repository

**Options:**

* `--template <name>` - Use specific template (default: vite-react-typescript)

#### tos serve

Start local development server.

```bash
tos serve
```

**What it does:**

* Reads `telemetry.config.json`
* Runs your `devServer.runCommand` (e.g., `vite --port 3000`)
* Provides development host UI
* Simulates TelemetryOS SDK environment

**Configuration:**

In `telemetry.config.json`:

```json
{
  "devServer": {
    "runCommand": "vite --port 3000",
    "url": "http://localhost:3000"
  }
}
```

## Development Workflow

### 1. Create Application

```bash
tos init weather-widget
cd weather-widget
```

### 2. Install Dependencies

```bash
npm install
```

### 3. Start Development

```bash
tos serve
```

Or use npm script:

```bash
npm run dev
```

### 4. Access Mount Points

Navigate to your configured mount points:

* **Settings:** http://localhost:3000/settings
* **Render:** http://localhost:3000/render

### 5. Make Changes

Edit files in `src/` directory. Hot module replacement (HMR) reloads changes automatically.

### 6. Test Functionality

Test SDK features using mock responses:

* Storage APIs work with localStorage
* All SDK methods return simulated responses
* State persists across page reloads

## Development Host UI

The development host UI provides a simulated TelemetryOS environment for testing applications.

### Features

* **Canvas Display** - Simulates device screen
* **Settings Panel** - Simulates admin settings sidebar
* **Scaling Container** - Responsive scaling for different screen sizes
* **SDK Bridge** - Mock SDK responses for local development
* **Local Storage** - Persistent storage simulation

### Using the Host UI

```bash
tos serve
```

Access at configured URL (typically http://localhost:3000).

**Interface Components:**

* **Canvas** - Displays render mount point
* **Sidebar** - Displays settings mount point
* **Controls** - Scale, theme, responsive testing

## Mock SDK Behavior

During local development, SDK methods return mock data:

### Storage

```typescript
// Works locally using localStorage
await store().instance.set('key', 'value');
const value = await store().instance.get('key');

// Subscriptions work with localStorage events
store().instance.subscribe('key', (value) => {
  console.log('Value changed:', value);
});
```

### Media

```typescript
// Returns sample media data
const media = await media().getAllByTag('featured');
// media contains mock MediaContent objects
```

### Playlist & Overrides

```typescript
// Operations succeed but don't affect actual playback
await playlist().nextPage(); // Returns true
await overrides().setOverride('alert'); // Returns true
```

### Accounts & Users

```typescript
// Returns mock account and user data
const account = await accounts().getCurrent();
// account = { id: 'mock-account-id' }
```

## Testing Patterns

### Manual Testing

**Settings Mount Point:**

1. Navigate to `/settings`
2. Configure application settings
3. Save to storage
4. Verify UI updates

**Render Mount Point:**

1. Navigate to `/render`
2. Verify subscription to settings
3. Check display updates when settings change
4. Test all display states

### Browser DevTools

Use Chrome/Firefox DevTools for debugging:

**Console:**

```javascript
// Access SDK directly in console
telemetry.store().instance.get('key')
telemetry.playlist().nextPage()
```

**Application Tab:**

* View localStorage (storage simulation)
* Inspect session storage
* Check service workers

**Network Tab:**

* Monitor external API calls
* Check proxy requests
* Verify resource loading

### React DevTools

Install React DevTools extension:

* Inspect component tree
* View props and state
* Profile performance
* Debug hooks

## Common Development Issues

### SDK Not Configured Error

**Error:** `SDK is not configured`

**Fix:** Call `configure()` before using SDK methods:

```typescript
import { configure } from '@telemetryos/sdk';

configure('my-app-name'); // Must match telemetry.config.json
```

### Mount Point Not Loading

**Error:** 404 or blank page

**Fix:** Check routing in `App.tsx`:

```typescript
const path = window.location.pathname;

if (path === '/settings') return <Settings />;
if (path === '/render') return <Render />;
```

### Hot Reload Not Working

**Issue:** Changes don't appear automatically

**Fixes:**

* Restart dev server (`tos serve`)
* Check Vite config for HMR settings
* Clear browser cache
* Check for TypeScript errors

### Storage Not Persisting

**Issue:** Data clears on refresh

**Cause:** Using wrong storage scope

**Fix:** Use instance or application scope:

```typescript
// ✅ Persists across reloads
await store().instance.set('key', 'value');

// ❌ May not persist in dev environment
await store().device.set('key', 'value');
```

## Building for Production

### Build Command

```bash
npm run build
```

Creates production files in `dist/` directory.

### Build Output

```
dist/
├── index.html
├── assets/
│   ├── index-abc123.js
│   └── index-def456.css
└── telemetry.config.json
```

**Important:** `telemetry.config.json` must be in build output.

### Verify Build

Check that build contains:

* ✅ All HTML files
* ✅ All assets (JS, CSS, images)
* ✅ telemetry.config.json at root
* ✅ Correct mount point paths

## Deployment to TelemetryOS

TelemetryOS provides three deployment methods. **GitHub integration is strongly recommended** for automatic builds and seamless updates.

### Method 1: GitHub Integration (Recommended)

The preferred deployment method with automatic building and updates.

**Workflow:**

1. **Create GitHub Repository**
   ```bash
   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://github.com/your-org/your-app.git
   git push -u origin main
   ```

2. **Connect in Studio**
   * Log in to TelemetryOS Studio (studio.telemetryos.com)
   * Navigate to Applications section
   * Click "New Application"
   * Select "GitHub Integration"
   * Connect your GitHub repository
   * Select branch to watch (e.g., `main`)

3. **Automatic Building**
   * TelemetryOS watches for changes via GitHub webhooks
   * On push, builds application in container
   * Deploys to TelemetryOS infrastructure
   * URL and hosting managed transparently

4. **Use in Playlists**
   * Add application to playlists
   * Position as region on page (or full screen)
   * Configure using settings mount point
   * Assign to devices

**Benefits:**

* ✅ Automatic updates on every push
* ✅ GitHub Actions integration
* ✅ Version history and rollback
* ✅ Collaborative development workflow
* ✅ No manual build steps

### Method 2: Zip File Upload

Upload a pre-built application archive directly.

**Workflow:**

1. **Build Your Application**
   ```bash
   npm run build
   cd dist
   zip -r ../my-app.zip .
   ```

2. **Upload to Studio**
   * Navigate to Applications section
   * Click "New Application"
   * Select "Upload Archive"
   * Upload your zip file
   * Platform extracts and validates

3. **Manual Updates**
   * Build locally
   * Create new zip
   * Upload to replace previous version

**When to Use:**

* Quick prototypes or testing
* No access to GitHub
* One-time or infrequent updates

**Limitations:**

* ❌ No automatic updates
* ❌ Manual build and upload process
* ❌ No version history
* ❌ No collaborative workflow

### Method 3: Generic Git Repository

Connect any Git repository (GitLab, Bitbucket, self-hosted).

**Workflow:**

1. **Configure Git Repository**
   * Push code to your Git hosting service
   * Get repository URL (HTTPS or SSH)
   * Generate deploy key if using SSH

2. **Connect in Studio**
   * Navigate to Applications section
   * Click "New Application"
   * Select "Generic Git Repository"
   * Enter repository URL
   * Add deploy key if needed
   * Select branch to watch

3. **Webhook Setup (Optional)**
   * Configure webhook on your Git host
   * Points to TelemetryOS webhook endpoint
   * Triggers builds on push

**When to Use:**

* Using GitLab, Bitbucket, or self-hosted Git
* GitHub not available in your organization
* Need flexibility with Git hosting

**Benefits:**

* ✅ Similar to GitHub integration
* ✅ Automatic builds (with webhooks)
* ✅ Version control workflow

**Setup Required:**

* Deploy keys for private repositories
* Webhook configuration for automatic builds

### Deployment Method Comparison

| Feature | GitHub | Zip Upload | Generic Git |
|---------|--------|------------|-------------|
| **Automatic Updates** | ✅ Yes | ❌ No | ✅ With webhooks |
| **Build Automation** | ✅ Yes | ❌ Manual | ✅ Yes |
| **Version History** | ✅ GitHub | ❌ No | ✅ Git |
| **Setup Complexity** | 🟢 Easy | 🟢 Easy | 🟡 Medium |
| **Collaboration** | ✅ Yes | ❌ No | ✅ Yes |
| **Rollback** | ✅ Easy | ❌ Manual | ✅ Easy |

### Recommendation

**Use GitHub integration** unless you have specific requirements:

* Seamless developer experience
* Automatic builds on every push
* Native GitHub Actions support
* Easy collaboration and code review
* Simple rollback to previous versions

**Use Zip Upload** only for:

* Quick testing or prototypes
* One-time deployments
* Situations without Git access

**Use Generic Git** when:

* Organization uses GitLab/Bitbucket
* GitHub is not available
* Self-hosted Git is required

### Build Configuration

TelemetryOS reads your `telemetry.config.json` and uses standard build commands:

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}
```

**Build Process:**

1. Clones repository
2. Installs dependencies (`npm install`)
3. Runs build command (`npm run build`)
4. Validates output
5. Deploys to CDN
6. Makes available in Studio

### Accessing Settings

Once deployed, settings mount point is accessible:

1. Open playlist in Studio
2. Click on your application region
3. Settings sidebar opens automatically
4. Shows your `/settings` mount point

### Application URLs

TelemetryOS manages all URLs transparently:

* No need to configure domains
* No need to manage SSL certificates
* Automatic CDN distribution
* Globally distributed hosting

## Debugging Production

### Browser Console

Applications run in iframes on devices. Use remote debugging:

**Android:**

* Enable USB debugging
* Connect via Chrome DevTools
* Inspect iframe

**Desktop Players:**

* Access local debugging interface
* View console logs
* Inspect network requests

### Platform Logs

View logs in TelemetryOS Studio:

* Application build logs
* Runtime error logs
* Device console logs

## Best Practices

### 1. Test Locally First

```bash
# Always test before committing
tos serve
# Test all mount points
# Verify functionality
# Check for errors
```

### 2. Version Control

```bash
# Commit working changes
git add .
git commit -m "Add weather display feature"
git push origin main
```

### 3. Environment Variables

Use environment variables for configuration:

```typescript
// vite supports import.meta.env
const API_KEY = import.meta.env.VITE_API_KEY;
```

**.env.local:**

```
VITE_API_KEY=your-api-key-here
```

### 4. Test Different Scenarios

* Configure settings, then view render
* Test with no configuration
* Test error states
* Test loading states
* Test different data combinations

### 5. Performance Testing

```typescript
// Monitor performance
console.time('data-fetch');
const data = await fetchData();
console.timeEnd('data-fetch');
```

## Tips

1. **Use HMR** - Saves time during development
2. **Check browser console** - Catch errors early
3. **Test both mount points** - Settings and render work together
4. **Use TypeScript** - Catch errors before runtime
5. **Test on target resolution** - Use responsive mode in DevTools

## Next Steps

* **[Quick Start](../quick-start.md)** - Create your first application
* **[Configuration](../configuration.md)** - Configure telemetry.config.json
* **[Code Examples](./code-examples.md)** - See complete applications