npm package: @juuno-sdk/app-simulator
Description: Test simulator for external Juuno apps - loads and displays apps in production-like environment
Author: Juuno
Latest version: 1.0.4

# Juuno App Simulator

Test your external Juuno apps in a production-like environment.

## What This Does

The App Simulator loads your external app and displays it in a split-screen view:

- **Left**: Player view (how your app appears on screens)
- **Right**: Configuration UI (your app's settings interface)

This simulates the real Juuno platform environment using import maps, just like production.

## Installation

```bash
npm install --save-dev @juuno-sdk/app-simulator
```

## Usage

### Option 1: CLI

```bash
# Point to your dev server
npx juuno-simulator --app=http://localhost:3000

# Or point to a deployed URL
npx juuno-simulator --app=https://cdn.example.com/my-app/
```

### Option 2: npm Scripts

Add to your `package.json`:

```json
{
  "scripts": {
    "dev": "vite",
    "test:player": "juuno-simulator --app=http://localhost:3000"
  }
}
```

Then run:

```bash
# Terminal 1: Your app dev server
npm run dev

# Terminal 2: Simulator
npm run test:player
```

## How It Works

1. **Your App**: Runs on your dev server (e.g., `localhost:3000`)
2. **Simulator**: Loads at `localhost:5004`
3. **Import Maps**: Simulator loads your app via ES module import
4. **Live Updates**: Changes in your app reflect immediately

## Requirements

Your app must:

- Export ES modules
- Provide player and config components
- Build with externalized dependencies:
  ```js
  // vite.config.ts
  export default {
    build: {
      lib: {
        entry: './src/index.ts',
        formats: ['es'],
        fileName: 'index',
      },
      rollupOptions: {
        external: ['vue', '@juuno-sdk/app-sdk'],
      },
    },
  };
  ```

## Development Workflow

The simulator works with built app bundles to match the production architecture.

**Terminal 1: Auto-rebuild your app**

```bash
cd my-juuno-app
npm run build:watch
# Watches for changes and rebuilds automatically
```

**Terminal 2: Serve your app bundle**

```bash
cd my-juuno-app
npx serve dist -l 3000 --cors
# Serves the built bundle at localhost:3000
```

**Terminal 3: Start the simulator**

```bash
npx juuno-simulator --app=http://localhost:3000/index.js
# → localhost:5004
```

**Development Flow:**

1. Edit your app's source code
2. Auto-rebuild happens in background (100-500ms)
3. Manually refresh browser at http://localhost:5004
4. See changes reflected in the simulator

**Note:** This workflow matches production closely (import maps + static bundles) but doesn't support HMR.

## CLI Options

```bash
juuno-simulator [options]

Options:
  --app <url>       URL of your external app (required)
  --port <number>   Port for simulator (default: 5004)
  --help            Show help
```

## Troubleshooting

### CORS Errors

If you see CORS errors, your dev server needs to enable CORS:

```js
// vite.config.ts
export default {
  server: {
    cors: true,
  },
};
```

### Module Not Found

Ensure your app exports the required components:

```ts
// src/index.ts
export { MyAppSlide } from './MyAppSlide.vue';
export { MyAppConfig } from './MyAppConfig.vue';
export { defaultMeta } from './settings';
```

### Import Map Issues

The simulator uses import maps to load dependencies. If you see import errors, check that your app properly externalizes `vue` and `@juuno-sdk/app-sdk`.

## Example

See [@juuno-sdk/app-sdk-example](../app-sdk-example) for a complete working example.

## Related Packages

- **@juuno-sdk/app-sdk**: SDK for building external apps
- **@juuno-sdk/app-sdk-example**: Example external app demonstrating the workflow