Skip to main content

Hot reload

Save a file, and every attached target (simulator and devices) reloads in well under two seconds, usually much less. This page explains exactly what happens, so the behavior never surprises you.

What a reload does​

  1. kog dev recompiles incrementally (typically < 300 ms) and pushes the new bundle to each attached target: the simulator over a local WebSocket dev hub, and a USB-connected board over the framed serial dev-link. Hot reload to a physical board is USB-only; there is no Wi-Fi code-push path.
  2. The target tears down the current app: effects are disposed, JS-held hardware claims (pins, buses, PWM channels) are released, and the current screen's widgets are deleted.
  3. The new bundle is evaluated in place and the app remounts. PSRAM boards assemble it in RAM; the no-PSRAM CYD streams it into an isolated alternating flash scratch region. The installed app and OTA staging region are untouched on both paths.
  4. Navigation state is not preserved: the new JS context starts fresh, so the app remounts at its initial route (the router's initialEntries, or /).

What is and isn't preserved​

Preserved across reload
Current route + params❌ (the app remounts at its initial route)
useStorage values❌ (v1 keeps them in memory; NVS persistence is a follow-up)
useState / in-memory state❌ (remounts fresh in v1)
Hardware claims❌ (released and re-claimed by the new code, which is what you want)

State-preserving Fast Refresh (keeping useState values across reloads) is designed into the runtime's architecture and planned post-v1.

Connecting to a board​

kog dev auto-detects a plugged-in board and attaches to it alongside the simulator (use --sim for the simulator only, or --port <p> to pick a specific serial port). To establish the link, it pulses a reset on connect. The board announces itself once at boot, so kog dev reboots it to catch that announcement, exactly the way opening the port in a browser does. You'll see a Board linked … line once the handshake and ABI check pass; from then on every save hot-reloads to glass. If no board is found, kog dev just runs the simulator.

CYD tier (bare ESP32, no PSRAM)

The CYD is the most RAM-constrained blessed board. Its dev-link holds only one 4 KB wire chunk at a time and streams larger apps into one of two isolated flash scratch regions; it does not reserve a bundle-sized RAM buffer. MQuickJS then executes the relocated bytecode in place from flash, leaving the 96 KB JS arena and networking headroom available to the app. A pre-transfer ready handshake keeps the host from sending chunks while the device erases the inactive scratch region.

Errors during development​

  • Compile errors never reach the device: kog dev prints them in your terminal (COMPILE ERROR: …) with the file and line, and the targets keep running the last good build.
  • Runtime errors (uncaught exceptions) are reported in the kog dev terminal with their stack, mapped back to your files (error locations).
  • console.log/warn/error from every target streams to the kog dev terminal, labeled by target.