Ecosystem & Configuration

These pages cover the tools around Cuttlefish: how to create a new project, describe a board so Cuttlefish understands it, handle custom hardware designed in typeCAD, and drive everything from the command line. If you’re new, start with Project Scaffolding to get a working project on your machine.

Topics

Package Ecosystem

The --target (or --board) flag picks a board from the catalog — the qualified west build -b argument (e.g. esp32s3_devkitc/esp32s3/procpu) or a bare board id. The catalog is generated from your installed Zephyr tree, so every board Zephyr supports is available with no board package; the first build materializes the project-local .cuttlefish/board.ts + board.json module from it. For custom PCBs designed in typeCAD, see Contracts.

Frameworks

Cuttlefish turns TypeScript into C++ through a framework — the layer that decides what C++ gets written. The framework pages cover what each one produces, what you need installed, and how to start a project.

See Frameworks for the full comparison.

Quick Start

Create a new project in one command:

npx @typecad/cuttlefish create my-project --target esp32s3_devkitc
cd my-project
npm run compile

Dependencies are installed automatically by create. Available targets for --target: native (desktop) or any board from the catalog — a bare board id like esp32s3_devkitc or a qualified target like esp32s3_devkitc/esp32s3/procpu. Run cuttlefish create with no --target for an interactive wizard.

Project Configuration

Each Cuttlefish project has a cuttlefish.config.ts that defines the entry point, board, framework, and output settings. This file is auto-generated by the scaffolder but can be customized:

import type { CuttlefishConfig } from '@typecad/cuttlefish/api';

const config: CuttlefishConfig = {
  entry: './src/main.ts',
  target: 'esp32s3',
  board: 'esp32s3_devkitc/esp32s3/procpu',
  framework: '@typecad/framework-zephyr',
  output: {
    outDir: './out',
  },
};

export default config;

Key fields:

• entry — the TypeScript (or .ui) entry point.
• target — optional architecture string, e.g. esp32, esp32s3, rp2040, nrf52.
• soc — the Zephyr SoC name for contract-based projects (e.g. 'stm32f411xe').
• board — the qualified Zephyr board target (e.g. 'esp32s3_devkitc/esp32s3/procpu'); the board module generates from the catalog on first build.
• framework — the code-generation package for your target.
• frameworkData.buildTarget — for custom-board projects, the generated board’s name (there is no upstream board target to set in board).
• output — outDir and optional framework, defines, extraFlags.
• zephyr — Zephyr build options: kconfig, cmakeArgs, probe/runner, runnerArgs.
• test — hardware-test runner settings (port, baudRate, timeout, include).
• psram — ESP32 PSRAM type ('opi' or 'quad'). When set, the framework emits the PSRAM-enabling Kconfig/FQBN option and BOARD_HAS_PSRAM, so large UI canvas allocations prefer external RAM. No effect on boards without PSRAM.

Use board for standard development boards, or soc + contract for custom PCBs designed in typeCAD (see Contracts).

Build Commands

The typical workflow uses these npm scripts (auto-generated in package.json):

npm run build     # Transpile to C++
npm run compile   # Transpile + compile
npm run upload    # Transpile + compile + upload
npm run monitor   # Transpile + compile + upload + serial monitor
npm run test:hw   # Hardware tests (cuttlefish-test)
npm run simulate  # Simulator tests (vitest on sim/)
npm run lint      # ESLint incl. generated transpiler-compatibility rules

Or use the CLI directly:

cuttlefish build --compile --upload --port COM4
cuttlefish build --watch --compile    # Auto-rebuild on changes
cuttlefish build --diagnostics        # Generate diagnostics report

See CLI Reference for all commands and flags.