Project Scaffolding

Create a new Cuttlefish project with the right configuration for your board and framework (the code-generation library for your target — Arduino, AVR, or native).

Create a Project

Using `npx` (no install required)

npx cuttlefish create my-project --target arduino-uno

Using the CLI

cuttlefish create my-project --target arduino-uno

Both forms invoke the same cuttlefish create scaffolder.

Interactive Wizard

If you run cuttlefish create without a --target flag, an interactive wizard will prompt you for:

Project name — defaults to the directory name
Target — choose from built-in targets
Framework — auto-detected from the target
Baud rate — serial monitor speed (default: 9600)

Non-Interactive Mode

Use flags to skip the wizard:

npx cuttlefish create my-project --target esp32-devkit --framework @typecad/framework-arduino --baud 9600

Flag	Description
`--target, -t <id>`	Target identifier (required for non-interactive)
`--board, -b <id>`	Alias for `--target`
`--framework, -f <pkg>`	Framework package (auto-detected from target)
`--baud <rate>`	Serial baud rate
`--no-sketch`	Skip generating the starter sketch
`--outDir, -o <path>`	Output directory (default: `./<name>`)

Built-in Targets

Target ID	MCU	Architecture	Build Target
`arduino-uno`	ATmega328P	AVR	`arduino:avr:uno`
`esp32-devkit`	ESP32-WROOM-32	ESP32	`esp32:esp32:esp32`
`esp32s3`	ESP32-S3	ESP32-S3	`esp32:esp32:esp32s3`
`native`	—	Desktop	—

Additional targets can be registered by framework or board packages.

Generated Project Structure

my-project/
  package.json           # Scripts and dependencies
  tsconfig.json          # TypeScript config for Cuttlefish
  cuttlefish.config.ts   # Transpiler configuration
  cuttlefish-env.d.ts    # Type declarations Cuttlefish adds for you
  .gitignore
  src/
    sketch.ts            # Starter blink sketch

`package.json`

Includes scripts for the common workflow:

npm run build — transpile to C++
npm run compile — transpile and compile
npm run upload — transpile, compile, and upload
npm run monitor — open serial monitor

`cuttlefish.config.ts`

The main configuration file with entry point, board, framework, and output settings:

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

const config: CuttlefishConfig = {
  entry: './src/sketch.ts',
  target: 'avr',
  board: '@typecad/board-arduino-uno',
  framework: '@typecad/framework-arduino',
  frameworkData: { buildTarget: 'arduino:avr:uno' },
  output: { framework: 'arduino', optimize: 'size', outDir: './out' },
};

export default config;

Custom Hardware (typeCAD Contract)

For custom PCBs designed in typeCAD, replace board with mcu + contract:

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

const config: CuttlefishConfig = {
  entry: './src/sketch.ts',
  target: 'avr',
  mcu: '@typecad/mcu-atmega328p',
  contract: './src/my-board.contract.json',
  framework: '@typecad/framework-arduino',
  frameworkData: { buildTarget: 'arduino:avr:uno' },
  output: { framework: 'arduino', optimize: 'size', outDir: './out' },
};

export default config;

See Contracts for the full guide on custom hardware integration.

Next Steps

After scaffolding:

cd my-project
npm install
npm run compile    # Build and compile
npm run upload     # Upload to board (connect via USB first)

On This Page