add-builtin-module

name	add-builtin-module
description	Step-by-step guide for adding new built-in JavaScript modules to mikrojs. Use this skill whenever the user wants to add a new JS-level module (not a raw C module), create a higher-level API wrapper around native C bindings, add a new "mikro/xxx" import, or asks about the TypeScript-to-bytecode pipeline, esbuild bundling, qjsc compilation, or how built-in modules are registered.

Adding a Built-in JS Module to mikrojs

Built-in JS modules provide higher-level APIs on top of native C modules. They're written in TypeScript, bundled with esbuild, compiled to bytecode with qjsc, and embedded in the firmware. Users import them as mikrojs/xxx.

There are two types:

1. Core builtins (mikrojs/xxx) - part of every firmware, compiled via CMake
2. Driver/board builtins (@mikrojs/driver-xxx) - registered via MIK_REGISTER_BUILTIN, only in firmware that includes the driver

---

Pipeline Overview

TypeScript source (.ts)
  -> esbuild bundle + minify (.js)     [scripts/bundle-runtime.js]
    -> qjsc bytecode compile (.h)      [scripts/compile-bytecode.sh]
      -> #include in builtins.cpp      [core] or MIK_REGISTER_BUILTIN [driver]
        -> Available at import("mikro/xxx") or import("@mikrojs/driver-xxx")

The pipeline is driven by the mikrojs_generate_bytecode() CMake function, which handles both the bundle and compile steps.

---

Adding a Core Builtin (mikrojs/xxx)

1. Create the TypeScript source

Create packages/@mikrojs/native/runtime/{name}/{name}.ts:

// packages/@mikrojs/native/runtime/example/example.ts
import * as native from 'native:example'
import {type Result, err, ok} from 'mikro/result'

export function read(channel: number): Result<number, {type: 'ReadFailed'}> {
  const result = native.read(channel)
  if (!result.ok) return err({type: 'ReadFailed' as const})
  return ok(result.value)
}

Key rules:

• Import native bindings from native:xxx (internal, not user-facing)
• Import other builtins from mikrojs/xxx
• Both native:* and mikrojs/* are marked external by esbuild
• Keep code minimal; every byte becomes firmware flash

2. If needed: create the native C module

Follow the add-native-module skill to create the native:xxx native module with MIK_REGISTER_MODULE().

3. Add to the RUNTIME_MODULES list

packages/@mikrojs/native/CMakeLists.txt and packages/@mikrojs/firmware/components/mikrojs/CMakeLists.txt both call mikrojs_generate_bytecode() with the module list:

mikrojs_generate_bytecode(
    RUNTIME_DIR "${MIK_RUNTIME_DIR}"
    MODULES result fetch i2c neopixel pin pwm rtc sleep spi sntp stdio sys wifi example
    MODULE_PREFIX "mikro"
    SYMBOL_PREFIX "mikro"
    TARGET gen_bytecode
)

Add your module name to the MODULES list in both files.

4. Include in builtins.cpp

packages/@mikrojs/native/src/builtins.cpp - Add the include and table entry:

// Add with the other gen/ includes (alphabetical order)
#include "gen/mikrojs_example.h"

// Add to the builtins[] table (alphabetical order)
static const mik_builtin_t builtins[] = {
    // ...
    {"mikro/example", mikrojs_example_bytecode, mikrojs_example_bytecode_size},
    // ...
    {NULL, NULL, 0},
};

5. Add type declarations (optional but recommended)

Create type declarations so TypeScript users get autocomplete.

6. Build and verify

pnpm run build:lib     # standalone library (generates bytecode + compiles)
cd esp32 && idf.py build  # ESP-IDF firmware

---

Adding a Driver/Board Builtin (@mikrojs/driver-xxx)

For driver packages that provide their own JS runtime wrappers.

1. Create the TypeScript source

Create runtime/{name}/{name}.ts in the driver package:

// packages/@mikrojs/driver-xxx/runtime/xxx/xxx.ts
import * as native from 'native:xxx'
import {type Result, err, ok} from 'mikro/result'

export function createDevice(config: DeviceConfig): Result<Device, InitError> {
  const result = native.init(config)
  if (!result.ok) return err({type: 'InitFailed', message: result.error ?? 'unknown'})
  return ok({
    /* device methods */
  })
}

2. Register the bytecode with MIK_REGISTER_BUILTIN

In the driver's C source file (same file as MIK_REGISTER_MODULE):

#include "gen/mik_driver_xxx_xxx.h"

MIK_REGISTER_BUILTIN(xxx, "@mikrojs/driver-xxx",
                      mik_driver_xxx_xxx_bytecode,
                      mik_driver_xxx_xxx_bytecode_size)

The bytecode header is generated by the driver's CMakeLists.txt.

3. Set up bytecode generation in CMakeLists.txt

include("${_BYTECODE_CMAKE}")
mikrojs_generate_bytecode(
    RUNTIME_DIR "${_RUNTIME_DIR}"
    MODULES xxx
    MODULE_PREFIX "@mikrojs/driver-xxx"
    SYMBOL_PREFIX "mik_driver_xxx"
    TARGET gen_driver_xxx_bytecode
    WORKING_DIRECTORY "${_DRIVER_ESP32_DIR}"
)
add_dependencies(${COMPONENT_LIB} gen_driver_xxx_bytecode)
target_include_directories(${COMPONENT_LIB} PRIVATE "${gen_driver_xxx_bytecode_INCLUDE_DIR}")

# Force linker to include the builtin registration
mikrojs_force_include_builtins(xxx)

4. How it works at runtime

When JS imports @mikrojs/driver-xxx:

1. Normalizer checks ext builtin list, passes name through unchanged
2. Loader calls mik__load_builtin() which finds the external builtin by name
3. Bytecode is deserialized and the module's native:xxx dependency is lazily resolved

---

Key Files

Path	Role
packages/@mikrojs/native/runtime/*/	Core builtin TypeScript sources
packages/@mikrojs/native/src/builtins.cpp	Core builtin table + external builtin loader
packages/@mikrojs/native/cmake/mikrojs_bytecode.cmake	Shared bytecode generation function
packages/@mikrojs/native/scripts/bundle-runtime.js	esbuild bundler
packages/@mikrojs/native/scripts/compile-bytecode.sh	qjsc compiler wrapper

---

Checklist

Core builtin

1. TypeScript source: packages/@mikrojs/native/runtime/{name}/{name}.ts
2. Native C module if needed (see add-native-module skill)
3. Module added to MODULES list in both CMakeLists.txt files
4. Generated header included in builtins.cpp
5. Table entry added to builtins[] array
6. Type declarations added (optional)

Driver builtin

1. TypeScript source: runtime/{name}/{name}.ts in driver package
2. MIK_REGISTER_BUILTIN() in driver's C source
3. mikrojs_generate_bytecode() in driver's CMakeLists.txt
4. mikrojs_force_include_builtins() in driver's CMakeLists.txt
5. Type declarations added (optional)