Skip to main content
Craft Agents uses esbuild for the main and preload processes, and Vite for the renderer process. All build scripts are managed through Bun.

​
Build Commands Overview

The build process is split into several stages for flexibility: 
bun run electron:build

​
Build Process Breakdown

1

Main Process

Build the Electron main process using esbuild:
bun run electron:build:main
This compiles the main process TypeScript code from apps/electron/src/main/ into optimized JavaScript.
2

Preload Scripts

Build the context bridge preload scripts:
bun run electron:build:preload
Compiles the preload scripts that expose secure APIs to the renderer process.
3

Renderer Process

Build the React UI using Vite:
bun run electron:build:renderer
Bundles the renderer process with all React components, shadcn/ui, and Tailwind CSS v4.
4

Resources and Assets

Copy additional resources and assets:
bun run electron:build:resources

​
Creating Distributions

Use electron-builder to create platform-specific installers and packages.

​
All Platforms

bun run electron:dist
This builds for your current platform using the configuration in electron-builder.yml.

​
Platform-Specific Builds

bun run electron:dist:mac
Cross-platform builds may require additional setup. For example, building for Windows on macOS requires Wine.

​
Build Output

Built distributions are created in the project root: 
craft-agents-oss/
├── dist/                      # electron-builder output
│   ├── mac/                   # macOS builds
│   │   └── Craft Agents.app
│   ├── win/                   # Windows builds
│   │   └── Craft Agents.exe
│   └── linux/                 # Linux builds
│       └── craft-agents
└── apps/electron/
    └── dist/                  # Intermediate build artifacts
        ├── main/
        ├── preload/
        └── renderer/

​
Development vs Production

​
Development Build

bun run electron:dev
Features:
  • Hot module replacement (HMR)
  • Source maps enabled
  • Debug logging on by default
  • React DevTools integration
  • Unminified code for debugging

​
Production Build

bun run electron:build
Features:
  • Minified and optimized code
  • Tree-shaking to reduce bundle size
  • Production React build (no dev warnings)
  • Source maps optional
  • Environment-specific optimizations

​
Type Checking

Always run type checks before building for distribution: 
bun run typecheck:all
This checks:
  • packages/core - Type definitions
  • packages/shared - Business logic
  • packages/session-tools-core - Session tools
Type checking runs separately from the build process. Always verify types before creating distributions.

​
Linting

Ensure code quality before building: 
bun run lint

​
Additional Build Scripts

​
Playground Development

Test UI components in isolation: 
bun run playground:dev
Opens a development playground at http://localhost:5173/playground.html.

​
Release Script

Automated release process: 
bun run release
This script is typically used by maintainers for official releases. It may modify version numbers and create git tags.

​
Build Configuration

The Electron Builder configuration is defined in electron-builder.yml at the project root:
electron-builder.yml
appId: do.craft.agents
productName: Craft Agents
directories:
  buildResources: apps/electron/build
  output: dist
files:
  - apps/electron/dist/**/*
  - packages/**/dist/**/*

​
Troubleshooting

​
Build Fails with Type Errors

Run type checking first to identify issues: 
bun run typecheck:all

​
Missing Dependencies

Reinstall dependencies: 
rm -rf node_modules
bun install

​
Stale Build Cache

Clean all build artifacts: 
bun run electron:clean
bun run electron:build

​
Platform-Specific Build Issues

Make sure you have the required platform tools:
  • macOS: Xcode Command Line Tools
  • Windows: Visual Studio Build Tools or Visual Studio
  • Linux: Standard build tools (build-essential on Debian/Ubuntu)

​
Next Steps

Setup

Review development environment setup

Guidelines

Learn contribution guidelines and best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us