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

Topic	What you’ll learn
Project Scaffolding	Create new Cuttlefish projects with `cuttlefish create`
Board Definitions	Use or create board definition packages
Contracts	Use typeCAD contracts for custom hardware
CLI Reference	Full command-line reference for `cuttlefish`

Package Ecosystem

Package	Purpose
`@typecad/cuttlefish`	Turns TypeScript into C++ for native, Arduino, and direct hardware targets
`@typecad/hal`	Hardware Abstraction Layer — the parts you call in your code
`@typecad/ui`	HTML/CSS-driven UI authoring library for microcontrollers
`@typecad/expect`	Hardware test framework — vitest-style assertions over serial
`@typecad/simulator`	Hardware simulation runtime for Node.js
`@typecad/mcu-atmega328p`	MCU definition for ATmega328P
`@typecad/mcu-esp32`	MCU definition for ESP32
`@typecad/mcu-esp32s3`	MCU definition for ESP32-S3
`@typecad/framework-avr`	AVR native register-level code generation
`@typecad/framework-arduino`	Arduino framework code generation
`@typecad/framework-native`	Native C++ for desktop builds (g++/clang++)
`@typecad/board-arduino-uno`	Board definition for Arduino Uno Rev3
`@typecad/board-esp32-devkit`	Board definition for ESP32 DevKit v1
`@typecad/board-esp32s3`	Board definition for ESP32-S3

Quick Start

Create a new project in one command:

npx cuttlefish create my-project --target arduino-uno
cd my-project
npm install
npm run compile

Available targets for --target: native (desktop), arduino-uno, esp32-devkit, esp32s3. 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, target architecture, MCU, 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/sketch.ts',
  target: 'esp32',
  mcu: '@typecad/mcu-esp32',
  board: '@typecad/board-esp32-devkit',
  framework: '@typecad/framework-arduino',
  frameworkData: {
    buildTarget: 'esp32:esp32:esp32',
  },
  output: {
    framework: 'arduino',
    optimize: 'size',
    outDir: './out',
  },
};

export default config;

Key fields:

entry — the TypeScript (or .ui) entry point.
target — architecture: avr, esp32, esp32s3, or native.
mcu — the low-level chip pin/port definitions package (e.g. @typecad/mcu-esp32).
board — the board-level pin aliases and peripheral mappings (e.g. @typecad/board-esp32-devkit).
framework — the code-generation strategy package.
frameworkData.buildTarget — the FQBN (the board ID Arduino uses) passed to arduino-cli.
output — framework (matching the strategy), optimize (size/speed), outDir.

Use board for standard development boards, or mcu + 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   # Open serial monitor

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.

On This Page