Back to blog

Monorepo Mastery: Turborepo for AI-First Poly-Applications

6 min read

TL;DR

  • Managing monorepos with diverse applications (CLI, web, desktop) leads to build complexity, slow CI, and inconsistent tooling.
  • Turborepo unifies and optimizes these heterogeneous workloads through intelligent caching and task graph execution, delivering fast, consistent builds.

The Monorepo Multi-Headed Beast: Why Heterogeneous Applications Strain Traditional Approaches

AI-first startups frequently develop a suite of interconnected products within a single repository. This often includes:

  • Core AI Models: Implemented in Python, often with performance-critical C++/CUDA extensions.
  • CLI Tools: For data ingestion, model interaction, and pipeline orchestration, potentially in Python, Go, or Node.js.
  • Web Frontends: Dashboards, annotation tools, and user interfaces, typically built with TypeScript/React/Next.js.
  • Desktop Applications: For specialized workflows requiring local processing or rich graphical interfaces, often using Electron or Tauri.

Housing such diverse applications in a monorepo quickly exposes severe architectural pain points. Build systems become a patchwork of npm scripts, poetry commands, cargo build invocations, and custom Makefiles. This leads to:

  • Inconsistent Tooling and Workflows: Developers must context-switch between disparate build and dependency management paradigms.
  • Redundant Dependency Management: Each application often manages its own node_modules, Python virtual environments, or target directories, leading to bloated disk usage and duplicated effort.
  • Slow, Non-Incremental CI/CD: Without a unified orchestrator, CI pipelines rebuild everything from scratch, even for minor changes, significantly increasing feedback cycles.
  • Manual Build Order Orchestration: Ensuring that shared libraries or compiled AI artifacts are built before dependent applications is a manual, error-prone process.
  • Cache Invalidation Nightmares: Determining when a change in one language's codebase invalidates the build cache for another language's application becomes intractable.

This complexity erodes developer velocity and introduces instability, directly hindering the rapid iteration critical for AI product development.

Turborepo: The Unifying Engine for Poly-Applications

Turborepo addresses these challenges by providing a high-performance build system designed for monorepos. Its core value proposition lies in two mechanisms:

  1. Content-Addressable Caching: Turborepo hashes the inputs of each task (source code, dependencies, environment variables) and caches the outputs. If the inputs have not changed, it restores outputs from the cache, locally or remotely, instead of re-running the task. This makes builds incremental by default across all applications.
  2. Optimized Task Graph Execution: It understands the dependencies between tasks (build of app-a depends on build of package-b) and executes them in parallel, respecting the graph. This transforms a linear, sequential build process into an efficient, concurrent one.

Crucially, Turborepo is largely language-agnostic. It wraps existing build commands, abstracting away the underlying tooling. Your package.json scripts, poetry run commands, or cargo build invocations become individual nodes in Turborepo's global task graph.

Consider a monorepo structure:

.
├── apps/
│   ├── web/           # Next.js frontend
│   ├── cli/           # Python CLI tool
│   └── desktop/       # Electron app
└── packages/
    ├── ui/            # Shared React components
    ├── common-types/  # Shared TypeScript types, Protobuf definitions
    └── ai-models/     # Python package for AI model inference, compiled components

Turborepo's turbo.json configuration dictates how tasks are run and cached:

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "build/**", "lib/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    }
  },
  "globalDependencies": [
    "**/.env",
    "**/tsconfig.json",
    "**/pyproject.toml",
    "**/Cargo.toml",
    "**/Pipfile",
    "**/requirements.txt"
  ]
}

dependsOn: ["^build"] tells Turborepo to build all dependencies of a package before building the package itself. outputs specifies which files to cache. globalDependencies is critical for cross-language consistency, ensuring that changes to any core configuration file (e.g., Python's pyproject.toml or Rust's Cargo.toml) invalidate relevant caches globally.

Engineering a Coherent Build Graph

The power of Turborepo for poly-applications stems from carefully defining the task graph and managing cross-language dependencies.

Structuring for Interoperability:

  • apps/: Contains deployable applications. Each app's package.json (even for non-JS apps, used for Turborepo task definitions) defines its specific build steps.
  • packages/: Houses shared libraries, components, and core logic.
    • packages/ai-models: A Python package containing model weights, inference code, and potentially compiled C++ extensions. Its package.json might define a build script that calls poetry build.
    • packages/common-types: Contains protobuf definitions or shared TypeScript interfaces that might be consumed by both web and Python services. Its build script could generate code for both languages.

Integrating Diverse Toolchains: For a Python CLI tool in apps/cli, its package.json would define scripts that leverage poetry or pipenv:

// apps/cli/package.json
{
  "name": "cli",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "poetry install && poetry run pyinstaller --onefile main.py",
    "dev": "poetry run python main.py",
    "test": "poetry run pytest"
  }
}

Turborepo orchestrates these scripts. When turbo run build is executed from the monorepo root, Turborepo will:

  1. Check if apps/cli's build task, considering its inputs (source, pyproject.toml, poetry.lock), is cached.
  2. If not cached, execute poetry install && poetry run pyinstaller --onefile main.py.
  3. Cache the outputs (e.g., dist/main) for future use.

Failure Modes Addressed:

  • Stale Builds: No more rm -rf node_modules && npm install && rm -rf dist && npm run build. Turborepo's content-addressable caching guarantees that if inputs haven't changed, the output is consistent.
  • CI Bottlenecks: Parallel execution and remote caching dramatically reduce CI times. A full rebuild might take minutes; subsequent builds with minor changes take seconds.
  • Dependency Hell: While each language manages its own dependencies, Turborepo defines the order of operations. For instance, a web app might depend on a ui package, which in turn depends on compiled Protobuf definitions from common-types. Turborepo ensures common-types build runs first, then ui build, then web build.

Trade-offs:

  • Initial Setup Overhead: Configuring turbo.json and adapting existing build scripts requires upfront effort.
  • Careful Dependency Declaration: Misconfigured dependsOn or outputs can lead to incorrect caching or build failures.
  • Remote Caching Infrastructure: Leveraging remote caching requires a Vercel account or self-hosting an S3-compatible blob storage.

Optimizing for AI Workloads and Beyond

Turborepo shines in AI-first environments by enabling fine-grained control over complex build artifacts:

  • Python Integration with Compiled Extensions: For packages/ai-models containing C++/CUDA extensions, the build script might execute poetry build which, in turn, triggers compilation. Turborepo's outputs configuration must capture these compiled artifacts.

    // packages/ai-models/turbo.json (or in root turbo.json)
{
  "build": {
    "dependsOn": ["^build"],
    "outputs": ["dist/**/*.whl", "src/**/*.so", "src/**/*.pyd"] // Python wheel, shared objects
  }
}

    This ensures that when apps/cli or apps/desktop depends on ai-models, Turborepo can retrieve the pre-built Python package, including its compiled components.

  • Native Compilation (Rust/Go): Integrating Rust services or Go CLI tools is straightforward. Their package.json scripts define cargo build or go build commands, and outputs capture the resulting binaries.

    // apps/rust-service/package.json
{
  "name": "rust-service",
  "scripts": {
    "build": "cargo build --release"
  }
}
// turbo.json
{
  "build": {
    "outputs": ["target/release/*"]
  }
}

    Platform-specific builds can be managed with distinct tasks (e.g., "build:linux": "cargo build --target x86_64-unknown-linux-gnu --release").

  • Docker Image Optimization: Turborepo enables highly optimized Docker multi-stage builds. Instead of copying the entire monorepo, a Dockerfile can leverage the Turborepo cache to only copy the built artifacts of a specific application and its direct dependencies. This results in smaller, faster-to-build images.

    # Dockerfile for apps/web
FROM node:18-alpine AS builder
WORKDIR /app
COPY . .
# Use Turborepo to build only the web app and its dependencies
RUN npx turbo prune --scope=web --docker
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/out/json .
COPY --from=builder /app/out/full/node_modules ./node_modules
COPY --from=builder /app/out/full/apps/web ./apps/web
# ... rest of the Dockerfile

    This turbo prune command creates a minimal context containing only what's needed for the target application, significantly reducing Docker build times and image sizes.

By embracing Turborepo, AI-first teams can tame the complexity of multi-language, multi-application monorepos. It provides the architectural backbone for rapid iteration, consistent environments, and efficient CI/CD, allowing engineers to focus on product innovation rather than build system maintenance.

Back to all posts