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

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 (lines 54-58), run:

# 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 and documented in .docs/scripts.md (line 10).

The Canonical Build Command

Execute the following from the repository root:

bun run build

This command invokes Turbo, which reads 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 (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 scripts section; 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 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 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 (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:

bun run dev

This command, documented in .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:

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 (lines 13-18), run the appropriate command for your target platform:

# 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}