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

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

Usage

Option 1: CLI

# 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:

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

Then run:

# 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:

  // 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

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

Terminal 2: Serve your app bundle

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

Terminal 3: Start the simulator

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

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:

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

Module Not Found

Ensure your app exports the required components:

// 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 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