Installation
Kog's entire toolchain installs through npm. You do not need ESP-IDF, CMake, a C compiler, Python, or Homebrew, either to develop or to flash.
Kog Studio runs the whole toolchain in your browser: editor, simulator, flashing, and live hot reload. Great for trying Kog before installing anything.
Requirements
- Node.js 20 or newer. The LTS lines (20 and 22) are recommended and best-tested; newer versions (including 24) work too.
kog doctorflags anything older than 20, where prebuilt native bindings may be missing. - A USB data cable if you have a board (charge-only cables, which power the board but carry no data, are the #1 support issue in embedded).
- No hardware? Skip straight to the simulator.
Create a project
npm create kog@latest my-app
cd my-app
npm run dev
create-kog scaffolds a complete TypeScript project (strict mode) from a template. It's non-interactive: the project name comes from the command, and there are no prompts. Your board's firmware is downloaded by kog flash when you flash, not at scaffold time. The desktop simulator isn't published as a prebuilt download yet; see the table below.
The npm packages aren't published yet. Until they ship, npm create kog@latest will 404. For now, install Kog from the repository: clone it and work in the workspace. This page describes the published flow.
Prefer plain JavaScript? Add --js for a JSX project instead of TSX:
npm create kog@latest my-app -- --js
Everything in Kog works the same in .jsx/.js files as it does in .tsx, including the compiler, CLI, hooks, components, and lint rules. TSX is just the default.
What gets installed
| Piece | How it arrives |
|---|---|
| Compiler, CLI, component library | Ordinary npm packages |
| Desktop simulator | Native binary. No prebuilt is published yet: build it from the repository (cmake -S native -B native/build && cmake --build native/build), or run kog dev --no-sim. Once prebuilts are published, kog simulate downloads one on first use. |
| Runtime firmware for your board | Prebuilt image, downloaded by kog flash |
| Serial drivers | None needed for ESP32-S3/C3/C6 boards (native USB). Older CH340/CP210x boards need a one-time OS driver; the CLI detects this and links you to it. |
Packages and types
The @kog/* packages ship built JavaScript in dist/ with its .d.ts type declarations, plus their TypeScript source in src/. Node, vitest, Metro and your editor load dist/ like any npm package. kog build asks for the kog-source export condition instead, so the code on your board is compiled from the same source the Kog repository tests. Inside the Kog repository itself, the packages point at src/ directly, with no build step.
A scaffolded app type-checks against those .d.ts files. Its tsconfig.json (or jsconfig.json) maps react and react-native to @kog/react and @kog/react-native and sets "types": [], so Node's types aren't pulled in. src/kog-env.d.ts adds the zero-import globals (fetch, WebSocket, WiFi, clock, …) and types require() for images only, so require('./logo.png') is an image source and require('./data.json') is a type error. Keep that file as it is.
Checking your setup
npx kog doctor
Verifies Node version, serial access, simulator binary, and (if a board is plugged in) that it can be seen. Every failure comes with the fix spelled out.