Building

​

Overview

1. Scala backend: Built with sbt (Scala Build Tool)
2. TypeScript frontend: Built with a custom build system based on esbuild

​

Building the Backend

​

sbt Console

​

Starting sbt

./lila.sh

• Validates Java installation
• Creates default config files if missing
• Launches sbt with configured JVM options

​

Common sbt Commands

// Compile all modules
compile

// Compile and run the application
run

// Remove build artifacts
clean

// Reload build definition after changing build.sbt
reload

// Run all tests
test

// Run specific test
testOnly lila.game.GameTest

​

Module-Specific Builds

// Compile only the game module
game/compile

// Run tests for user module
user/test

// Clean and compile rating module
rating/clean
rating/compile

​

Compilation Order

1. Level 1: core, coreI18n
2. Level 2: ui, common, tree
3. Level 3: db, room, search
4. Level 4: memo, rating
5. Level 5+: Feature modules (game, user, tournament, etc.)

​

Incremental Compilation

• Only changed files are recompiled
• Dependent modules are recompiled if needed
• Compilation state is cached

// Force full recompilation
clean
compile

​

Production Packaging

# In sbt console
Universal/packageBin

• Compiled classes
• Dependencies
• Startup scripts
• Configuration

​

Building the Frontend

​

Build Script

ui/build [options] [packages...]

​

Build Options

# Watch mode: rebuild on changes
ui/build -w
ui/build --watch

# Production build: minified, optimized
ui/build --prod
ui/build -p

# Clean build artifacts first
ui/build --clean
ui/build -c

# Debug mode: verbose output
ui/build --debug
ui/build -d

# Show help
ui/build --help
ui/build -h

​

Building Specific Packages

# Build analyse package
ui/build analyse

# Build multiple packages
ui/build analyse puzzle round

# Build with watch mode
ui/build -w analyse puzzle

​

Build Process

​

Build Output

public/
├── compiled/           # Bundled JavaScript and CSS
│   ├── analyse.6f3a9d2e.js
│   ├── analyse.8c2f5a3b.css
│   └── manifest.a1b2c3d4.json
├── hashed/            # Content-hashed assets
│   └── image.e5f6g7h8.png -> ../images/image.png
└── npm/               # Synced npm packages
    └── stockfish.wasm

​

Watch Mode

1. Monitors source files for changes
2. Rebuilds affected packages incrementally
3. Updates the manifest
4. Prints success/error messages

ui/build -w

Building analyse...
✓ Bundled analyse.ts → analyse.6f3a9d2e.js (1.2s)
✓ Compiled analyse.scss → analyse.8c2f5a3b.css (0.3s)
✓ Created manifest.a1b2c3d4.json

Watching for changes...

​

Full Build

​

Development Build Workflow

​

Internationalization Build

// In build.sbt
Compile / resourceGenerators += Def.task {
  I18n.serialize(
    sourceDir = new File("translation/source"),
    destDir = new File("translation/dest"),
    dbs = List("site", "arena", "emails", ...),
    outputDir = (Compile / resourceManaged).value
  )
}.taskValue

​

Optimization

​

Backend Optimization

• Incremental compilation: Only changed files
• Parallel compilation: Multiple modules at once (when possible)
• Dependency caching: Downloaded dependencies cached locally

​

Frontend Optimization

• Fast bundling: Written in Go, highly parallelized
• Tree shaking: Removes unused code
• Minification: Smaller file sizes (production mode)
• Code splitting: Shared chunks across modules
• Source maps: For debugging (development mode)

​

Production Optimizations

ui/build --prod

• Minification
• Dead code elimination
• Optimized chunk splitting
• Smaller source maps (or none)

​

Build Performance

​

Improving sbt Performance

1. Allocate more memory in .sbtopts:
   -J-Xms4g
   -J-Xmx16g
   
2. Use sbt server: Keep sbt running, don’t restart
   # Keep this terminal open
   ./lila.sh
   
3. Build specific modules:
   game/compile  // Instead of compile
   

​

Improving UI Build Performance

1. Build specific packages:
   ui/build analyse  // Instead of ui/build
   
2. Use watch mode: Incremental rebuilds are faster
   ui/build -w
   
3. Upgrade Node.js: Newer versions are faster

​

CI/CD Builds

# .github/workflows/build.yml
- name: Build UI
  run: ui/build --prod

- name: Test Scala
  run: sbt test

​

Troubleshooting

​

sbt Out of Memory

java.lang.OutOfMemoryError: Java heap space

-J-Xmx16g

​

UI Build Fails

# Check Node.js version
node -v  # Should be v24.11.1+

# Reinstall dependencies
rm -rf ui/node_modules
cd ui && pnpm install

# Clean build
ui/build --clean

​

Compilation Errors

// In sbt, clean and retry
clean
compile

// Or for specific module
game/clean
game/compile

​

Slow Builds

• Check system resources (CPU, RAM)
• Close other applications
• Use module-specific builds
• Keep sbt running (don’t restart)

​

Next Steps

• Learn about testing your builds
• Understand the module structure
• Explore UI development workflow

​

Additional Resources

• sbt documentation
• esbuild documentation
• ui/README.md