Turborepo Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Games monorepo utilizes Turborepo as its high-performance build system to orchestrate tasks across multiple applications and shared packages. It provides a structured way to manage the development lifecycle—including building, linting, and testing—ensuring that tasks are executed in the correct order based on internal dependencies while leveraging local and remote caching to optimize execution time.
Sources: README.md:14-16, turbo.json:1-20
Monorepo Structure
The project is organized into two primary directories: apps/ for executable services and packages/ for shared logic and definitions. This structure is defined in the root configuration to allow Turborepo to recognize the individual workspace members.
The diagram above illustrates the workspace hierarchy managed by Turborepo.
Sources: package.json:20-24, README.md:18-27
Pipeline Configuration
The turbo.json file defines a pipeline that specifies how different tasks relate to one another and what their expected outputs are. This ensures that a build in one package triggers necessary builds in its dependencies.
Task Definitions
| Task | Dependencies | Caching/Behavior | Outputs |
|---|---|---|---|
build | ^build | Enabled | .next/**, dist/** |
dev | None | Cache disabled, Persistent | N/A |
lint | ^build | Enabled | N/A |
test | ^build | Enabled | coverage/** |
clean | None | Cache disabled | N/A |
Sources: turbo.json:4-19
Build Dependency Logic
Turborepo uses the ^ symbol to denote "upstream" dependencies. For the build, lint, and test tasks, the configuration ensures that a package's dependencies must be built before the package itself can process the task.
Logic flow for the dependsOn: ["^build"] directive found in the pipeline.
Sources: turbo.json:5-7, apps/cyoa-engine/package.json:15-20
Workspace Interdependencies
The power of the Turborepo configuration is evidenced by the complex graph of internal workspace dependencies. Applications like cyoa-engine and mcp-connector depend on shared local packages using the workspace:* protocol.
| Consumer | Dependency | Version |
|---|---|---|
cyoa-engine | shared-types, mcp-sdk, story-engine | workspace:* |
mcp-connector | shared-types, mcp-sdk | workspace:* |
mcp-sdk | shared-types | workspace:* |
story-engine | shared-types | workspace:* |
Sources: apps/cyoa-engine/package.json:17-19, apps/mcp-connector/package.json:19-20, packages/mcp-sdk/package.json:13, packages/story-engine/package.json:12
Execution Commands
The root package.json provides convenience scripts that wrap the turbo CLI, allowing developers to execute tasks across the entire monorepo or filter by specific applications.
"scripts": {
"build": "turbo run build",
"dev": "turbo run dev",
"lint": "turbo run lint",
"test": "turbo run test",
"clean": "turbo run clean && rm -rf node_modules"
}
Sources: package.json:6-12
Filtering Tasks
Turborepo allows targeted execution using the --filter flag, which is used in this project to run individual services without invoking the entire graph:
- Frontend:
pnpm --filter cyoa-engine dev - MCP Connector:
pnpm --filter mcp-connector dev
Sources: README.md:129-133
Summary
The Turborepo configuration in this monorepo acts as the central orchestration layer. By defining a strict pipeline in turbo.json and leveraging pnpm workspaces, the system ensures that shared packages like shared-types and mcp-sdk are always built and available for the consumer applications (cyoa-engine, mcp-connector). This setup minimizes redundant builds through intelligent caching and provides a unified interface for the project's development lifecycle.