> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.
# bricks-ctor
> TypeScript SDK for building BRICKS applications as code
**bricks-ctor** is a TypeScript SDK that lets you define, build, and deploy [BRICKS](https://bricks.tools) applications entirely in code. Instead of working in a visual editor, you write TypeScript that compiles into the configuration the BRICKS runtime understands.
bricks-ctor is in **preview**. The API and tooling may change.
## 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 |
| **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
├── 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 (auto-generated)
```
All application logic is defined in TypeScript files. Running `bun compile` transforms them into the JSON configuration that the BRICKS runtime executes.
## Next steps
Set up your environment and create your first BRICKS project.