# How to Build the t3code Project: Complete Guide for the pingdotgg/t3code Monorepo

> Learn to build the t3code project with this complete guide. Easily compile contracts, web app, and server using bun run build and Turbo orchestration from the pingdotgg/t3code monorepo.

- Repository: [Ping.gg/t3code](https://github.com/pingdotgg/t3code)
- Tags: how-to-guide
- Published: 2026-04-18

---

**Run `bun run build` from the root to compile the contracts, web app, and server using Turbo orchestration.**

The `pingdotgg/t3code` repository is a monorepo that orchestrates a real-time code execution platform using **Bun** and **Turbo**. To build the t3code project from source, you must compile three distinct logical parts: shared contracts, a Vite-based React web application, and a Node.js WebSocket server.

## Prerequisites

Before building, ensure you have the Bun toolchain installed. The repository optionally supports `mise` for version management. According to [`README.md`](https://github.com/pingdotgg/t3code/blob/main/README.md) (lines 54-58), run:

```bash

# Optional: install mise toolchain

mise install

# Install all workspace dependencies

bun install .

```

## Build the t3code Project with Turbo

The canonical command to build the t3code project is defined in the root [`package.json`](https://github.com/pingdotgg/t3code/blob/main/package.json) and documented in [`.docs/scripts.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/scripts.md) (line 10).

### The Canonical Build Command

Execute the following from the repository root:

```bash
bun run build

```

This command invokes **Turbo**, which reads [`turbo.json`](https://github.com/pingdotgg/t3code/blob/main/turbo.json) to orchestrate the build pipelines for `@t3tools/contracts`, `@t3tools/web`, and `@t3tools/server` in the correct dependency order.

### What the Build Process Compiles

The monorepo contains three logical components that are compiled during the build:

1. **Contracts** (`packages/contracts`): Zod-based schemas are compiled to plain TypeScript types and JSON schemas for type-safe communication between client and server.
2. **Web** (`apps/web`): The Vite-based React UI is bundled into static assets in `apps/web/dist`.
3. **Server** (`apps/server`): The WebSocket server TypeScript is compiled to a single CommonJS entry point in `apps/server/dist`.

## Step-by-Step Build Process

The complete build workflow follows these stages:

| Step | What happens | Where in the repo |
|------|--------------|-------------------|
| **1. Install dependencies** | Installs all workspace packages and the Bun toolchain. | [`README.md`](https://github.com/pingdotgg/t3code/blob/main/README.md) (lines 54-58) describes `mise install` and `bun install .` |
| **2. Run the build** | Executes `bun run build`. Turbo resolves the three sub-projects: `@t3tools/contracts`, `@t3tools/web`, `@t3tools/server`. | Root [`package.json`](https://github.com/pingdotgg/t3code/blob/main/package.json) scripts section; [`turbo.json`](https://github.com/pingdotgg/t3code/blob/main/turbo.json) |
| **3. Contract generation** | Zod-based schemas are compiled to plain TypeScript types and JSON schemas used by both the server and the web client. | `packages/contracts` folder; compiled by the `build:contracts` step in Turbo |
| **4. Web compilation** | Vite bundles the React UI into static assets (`apps/web/dist`). | `apps/web` — [`vite.config.ts`](https://github.com/pingdotgg/t3code/blob/main/vite.config.ts) is invoked during the Turbo `build:web` task |
| **5. Server bundling** | The server TypeScript code is compiled to a single CommonJS entry (`apps/server/dist`). | `apps/server` — [`tsconfig.json`](https://github.com/pingdotgg/t3code/blob/main/tsconfig.json) and `tsup` (or Bun’s native TS compiler) are used in the `build:server` task |
| **6. Desktop artifact (optional)** | After the regular build, create a native desktop package (`.dmg`, `.AppImage`, `.exe`). | [`.docs/scripts.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/scripts.md) (lines 13-18) lists the desktop-artifact commands |

## Development vs Production Builds

The repository distinguishes between hot-reload development and production optimization.

### Hot Reload Development

For local development with instant feedback, use:

```bash
bun run dev

```

This command, documented in [`.docs/quick-start.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/quick-start.md) (lines 5-15), starts the development servers for both the web and server components with hot module replacement enabled.

### Production Build and Start

After running `bun run build`, launch the compiled application with:

```bash
bun run start

```

This starts the compiled WebSocket server and serves the static UI assets from `apps/web/dist` as implemented in the production entry point.

## Building Desktop Artifacts

To distribute the application as a native desktop binary, the build outputs can be packaged after the standard compilation.

According to [`.docs/scripts.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/scripts.md) (lines 13-18), run the appropriate command for your target platform:

```bash

# macOS DMG (default arm64)

bun run dist:desktop:dmg

# Linux AppImage

bun run dist:desktop:linux

# Windows NSIS installer

bun run dist:desktop:win

```

Additional flags such as `--signed` (for CI code-signing) and `--keep-stage` (to inspect intermediate files) are also supported.

## Summary

- **Install dependencies** with `bun install .` (optionally using `mise install` for toolchain management).
- **Build the entire project** by running `bun run build`, which uses Turbo to compile contracts, the Vite web app, and the WebSocket server in dependency order.
- **Develop locally** with `bun run dev` for hot reload, or **start production** with `bun run start` after building.
- **Package desktop binaries** using `bun run dist:desktop:<platform>` to create `.dmg`, `.AppImage`, or `.exe` installers.

## Frequently Asked Questions

### What build tool does t3code use?

The t3code project uses **Bun** as the JavaScript runtime and package manager, combined with **Turbo** to orchestrate the monorepo build pipeline. This setup is defined in the root [`package.json`](https://github.com/pingdotgg/t3code/blob/main/package.json) and [`turbo.json`](https://github.com/pingdotgg/t3code/blob/main/turbo.json) files.

### Do I need to build the contracts separately?

No, you do not need to build the contracts manually. When you run `bun run build` from the root, Turbo automatically resolves the dependency graph and compiles the `@t3tools/contracts` package before the web and server builds that depend on it.

### How do I create a desktop installer for t3code?

After running the standard build, use the platform-specific desktop distribution commands. Run `bun run dist:desktop:dmg` for macOS, `bun run dist:desktop:linux` for Linux, or `bun run dist:desktop:win` for Windows. These commands package the compiled web and server assets into native installers.

### What is the difference between `bun run dev` and `bun run build`?

`bun run dev` starts the development servers with hot module replacement for rapid iteration, while `bun run build` compiles the TypeScript, bundles the Vite React app, and prepares the WebSocket server for production deployment. After building, you must run `bun run start` to launch the production server.