CLI Development Server

Overview of Aircada's real-time hot-swapping development server and its WebSocket hot-reload pipeline.

Published: 7/10/2026

Developer Live-Reload Sync

Aircada CLI provides a real-time development mode (air dev) that establishes a localized WebSocket and HTTP server.

This mounts a high-performance, live-sync channel directly connecting your local filesystem with the active web-based AIRCADA STUDIO Panel viewport.

Browse the deep mechanics of hot-swapping:

Dev Server & Hot-Swapping Mechanics#

Technical breakdown of Chokidar file watchers, esbuild compilers, WebSocket telemetry, and APEX REST mutations.

Dual-Channel Communication Architecture

During live development sessions (air dev), the CLI dev server coordinates files, bundles, and remote APEX instructions across a WebSocket (Port 9005), HTTP server, and REST API mutations pipeline:

mermaid

graph TD
    subgraph Local Workspace
        A[File Watcher: Chokidar] -->|Detects Change| B[Builder: Scan + Gen virtual entry]
        B -->|Compile Bundle| C[Bundler: esbuild]
        C -->|Raw JS Code| D[Dev Server]
    end

    subgraph Dual Communication Channel
        D -->|WS: code-update / build-error| E(WebSocket Server - Port 9005)
        D -->|HTTP: GET /bundle.js| F(HTTP Server - Port 9005)
        D -->|HTTP: POST /api/apex/execute| G(REST APEX endpoint)
    end

    subgraph Aircada Studio - Live Web App
        E <-->|WS Link| H[Studio Runtime Engine]
        H -->|Hot Swap Bundle| I[Interactive Preview]
        H -.->|Trigger remote mutation| G
    end

    classDef local fill:#2a2b36,stroke:#4a50ff,stroke-width:2px,color:#fff;
    classDef comm fill:#1c1d24,stroke:#39c362,stroke-width:2px,color:#fff;
    classDef cloud fill:#202127,stroke:#e95420,stroke-width:2px,color:#fff;

    class A,B,C,D local;
    class E,F,G comm;
    class H,I cloud;

Step-by-Step Hot Swap Loop

1. File Watcher (Chokidar): Monitors your local src/ folder for TypeScript edits.

2. Incremental Builder (esbuild): Re-compiles your bundle into an optimized virtual distribution output in milliseconds upon change.

3. Telemetry Push: The Dev Server broadcasts a code-update WebSocket frame containing the raw JS bundle to the web dashboard runtime.

4. Interactive Swap: The Aircada Studio runtime intercepts the WebSocket event, immediately evaluates the new logic block, and hot-swaps it into the active browser spatial preview without refreshing or losing session state.

5. Dynamic Mutations (APEX REST): Interactive gestures or changes in Aircada Studio propagate remote mutation calls back to the REST APEX endpoint, maintaining synchronized local-to-cloud alignment.

Ephemeral Authentication Loopback Flow

Logging into the CLI (air login) coordinates securely with the browser without manual credentials copying via a custom loopback sequence: