bricks-ctor

bricks-ctor is a TypeScript SDK that lets you define, build, and deploy BRICKS applications entirely in code. Instead of working in a visual editor, you write TypeScript that compiles into the configuration the BRICKS runtime understands. The bricks-ctor tooling ships with the BRICKS CLI as the bricks ctor command group — there is no separate npm package to install.

Generated projects don’t depend on an npm package for BRICKS. The CLI materializes a typed bricks-ctor library into a local ctor/ directory, and the project’s tsconfig.json maps the bricks-ctor import alias to it — so import ... from 'bricks-ctor' works with no dependency.

Why code?

Type safety — catch errors at compile time with full TypeScript support
Version control — track changes with Git, review diffs, and collaborate
AI-assisted development — work with AI coding agents that can read and write your project files
Automation — deploy via CLI or CI/CD pipelines like GitHub Actions

Core concepts

A BRICKS application is a tree of composable entities. Here’s how they fit together:

Application
└── Subspace (feature/screen container)
    ├── Canvas (view/scene layout)
    │   └── Items (positioned Bricks or Subspace references)
    ├── Brick (UI component)
    ├── Generator (data/IO provider)
    ├── Data (state storage)
    ├── Animation (visual effects)
    └── Data Calculation (data transforms)

Subspaces

A subspace is a self-contained unit of functionality — think of it as a screen or feature module. Each subspace has its own bricks, generators, data, canvases, and animations. The application has a rootSubspace as its entry point.

Canvases

A canvas defines a view layout. It positions items (bricks or subspace references) on a grid using frame coordinates (x, y, width, height). Canvases support lifecycle events (firstEnter, enter, exit) and can switch between each other for navigation.

Bricks

Bricks are the visual building blocks — UI components that display content and handle interaction. Examples include:

Brick	Purpose
Text	Display text with styling
TextInput	Editable text field
RichText	Rich text with HTML content, multiple fonts, and inline images
Image	Display images
Video	Video playback
VideoStreaming	RTSP / RTMP live video streams
WebrtcStream	WebRTC video and audio stream
GenerativeMedia	AI-generated images and videos
WebView	Embedded web content
Lottie	`.json` and `.dotlottie` animations with speed, loop, and frame range control
Rive	`.riv` animations with state machine inputs, text runs, and artboard selection
Svg	SVG vector graphics
Chart	Data visualizations
Icon	FontAwesome 6 Pro icons
QrCode	QR code display
Camera	Live camera feed
Maps	Map display
Scene3D (Preview)	Real-time 3D scenes — glTF/USD models, primitives, lights, cameras, and interactive controls, rendered with WebGPU/WebGL
Rect	Container with background, border, shadow
Items	Data-driven list or grid from an array
Slideshow	Auto-advancing slides with transition effects

Bricks can be styled, animated, respond to press events, and have their properties dynamically bound to data.

Generators

Generators handle all external I/O and data processing. They connect your app to APIs, databases, hardware, AI models, and more. Each generator has outlets (output channels) that feed into data, and events that trigger actions. Categories of generators include:

Category	Examples
AI & LLM	Assistant, LLM (GGML/OpenAI/Anthropic/ONNX), Vector Store, Reranker
Speech	Text-to-Speech, Speech-to-Text, VAD, Realtime Transcription
Network	HTTP, WebSocket, GraphQL, MQTT, TCP, UDP, HTTP Server
Storage	File, SQLite, Data Bank, Media Flow
Hardware	Bluetooth LE, Serial Port, Camera, Keyboard
Control flow	Tick (timer), Alarm Clock, Step, Iterator, Watchdog
Other	WebRTC, Web Crawler, MCP, Thermal Printer

Data

Data nodes store application state. They are typed (string, number, boolean, array, object) and can be linked to brick or generator properties for reactive updates. When a generator outlet emits a value, the linked data updates, and any bricks bound to that data re-render automatically.

Data calculations

Data calculations are JavaScript functions that transform data. They run in a sandboxed environment with 25+ built-in libraries (lodash, moment, crypto, and more). Use them for formatting, parsing, or computing derived values.

Actions and events

Actions are commands triggered by events. Bricks and generators emit events (press, response, error, timer tick), and you wire them to actions like changing a canvas, updating data, triggering a generator, or running an animation.

Project structure

A BRICKS project has the following structure:

my-app/
├── application.json              # App metadata (name, ID, stage)
├── package.json
├── tsconfig.json
├── app.ts                        # Application entry point
├── root.ts                       # Root subspace definition
├── ctor/                         # Typed bricks-ctor library (generated by the CLI)
├── subspaces/
│   └── subspace-0/
│       ├── index.ts              # Subspace exports
│       ├── bricks.ts             # Brick definitions
│       ├── canvases.ts           # Canvas layouts
│       ├── generators.ts         # Generator configurations
│       ├── data.ts               # Data definitions
│       ├── animations.ts         # Animation configs
│       └── data-calc/            # Data calculation scripts
│           └── index.ts
├── automation-tests/             # E2E test definitions
├── CLAUDE.md / AGENTS.md         # AI agent instructions (optional)
└── .mcp.json                     # MCP server config (points at the CLI, auto-generated)

All application logic is defined in TypeScript files. Running bun compile (which runs bricks ctor compile under the hood) transforms them into the JSON configuration that the BRICKS runtime executes.

Next steps

Get started

Set up your environment and create your first BRICKS project.

Overview

AI tooling

Changelog

Why code?

Core concepts

Subspaces

Canvases

Bricks

Generators

Data

Data calculations

Actions and events

Project structure

Next steps

Get started

​Why code?

​Core concepts

​Subspaces

​Canvases

​Bricks

​Generators

​Data

​Data calculations

​Actions and events

​Project structure

​Next steps

Get started

Why code?

Core concepts

Subspaces

Canvases

Bricks

Generators

Data

Data calculations

Actions and events

Project structure

Next steps