Turborepo Best Practices

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• AGENTS.md
• turbo.json
• package.json
• README.md
• apps/dotori-note/package.json
• packages/ui-craft/package.json

Introduction

Turborepo serves as the primary build system and task orchestrator for the web-projects monorepo. It manages the execution of scripts across a diverse set of applications, shared libraries, and playgrounds, ensuring efficient builds through intelligent caching and dependency tracking.

The scope of Turborepo in this project encompasses the management of frontend frameworks (Astro, Next.js), UI libraries (React, Framer Motion), and specialized tools (Rust CLI). By centralizing task definitions in turbo.json, the repository maintains a consistent development workflow for all contributors.

Sources: CLAUDE.md:27-44, AGENTS.md:27-44, turbo.json:1-26

Task Orchestration and Pipelines

The core of the Turborepo implementation is the pipeline defined in turbo.json. This configuration determines how tasks depend on one another and which outputs should be cached to speed up subsequent executions.

Build and Test Dependencies

Tasks are structured so that high-level operations (like testing or type-checking) depend on the completion of upstream builds.

The diagram above illustrates the task dependency graph where testing and type-checking require a successful build of dependent packages.

Sources: turbo.json:4-25, CLAUDE.md:79-84, AGENTS.md:79-84

Pipeline Configuration Summary

Task	Persistent	Cache	Outputs	Dependencies
build	No	Yes	dist/**, .next/**	^build
dev	Yes	No	N/A	N/A
check-types	No	Yes	N/A	^check-types, ^build
test	No	Yes	N/A	^build
test:coverage	No	Yes	coverage/**	^build
format-and-lint	No	Yes	N/A	N/A

Sources: turbo.json:4-25

Workspace Architecture

The project utilizes bun workspaces to manage internal dependencies within the monorepo. This allows packages to reference each other without needing to be published to a registry.

Package Directory Structure

The monorepo is divided into three logical workspace categories:

• Apps (apps/): User-facing applications like dotori-note and noumenon-front.
• Packages (packages/): Shared libraries and configurations, such as @siluat/ui-craft and @siluat/typescript-config.
• Playgrounds (playgrounds/): Isolated environments for testing components or CLI tools locally.

Sources: package.json:43-47, CLAUDE.md:27-44, AGENTS.md:27-44

Workspace Dependency Management

Internal packages are linked using the workspace:* protocol. This ensures that the monorepo always uses the local, current version of a shared library during development and builds.

{
  "dependencies": {
    "@siluat/ui-craft": "workspace:*",
    "@siluat/shadcn-ui": "workspace:*"
  }
}

Sources: CLAUDE.md:58-61, AGENTS.md:58-61, apps/dotori-note/package.json:20-21

Development Workflow

Turborepo streamlines common developer tasks through standardized commands executed from the root of the repository.

Essential Commands

• turbo dev: Starts development servers for all applications concurrently.
• turbo run build: Compiles all packages and applications, respecting the dependency graph.
• turbo run static-check: A combined task that runs TypeScript type-checking and Biome linting across the entire workspace.
• turbo gen package: Utilizes @turbo/gen to scaffold new packages based on predefined templates.

Sources: package.json:13-22, CLAUDE.md:10-14, AGENTS.md:10-14, README.md:37-43

Generator Patterns

The repository uses turbo gen to maintain consistency when creating new modules. Templates are stored in the /templates directory to ensure all new packages follow the established structure for configuration, testing, and exports.

Sources: templates/README.md:1-5, package.json:28

Code Quality Standards

Turborepo works in conjunction with Biome and Lefthook to enforce standards before code is committed.

Task-Specific Best Practices

1. Colocation: Test files must be colocated with source files (e.g., foo.test.ts next to foo.ts) rather than in separate __tests__ directories.
2. Explicit Exports: UI libraries must use the ./react/* pattern in their exports field to allow consumer applications to import specific components.
3. Rust Integration: Rust packages (noumenon-gleaner) require a specialized flow where cargo build is followed by Node.js postbuild scripts to bridge the Rust and TypeScript environments.

Sources: CLAUDE.md:63-70, 82-83, AGENTS.md:63-70, 82-83, packages/ui-craft/package.json:11-13

Summary

Turborepo facilitates a high-performance monorepo environment for web-projects by managing complex task dependencies between disparate technologies like React, Astro, and Rust. By leveraging workspace protocols and centralized task definitions, the system ensures that builds are reproducible, cached effectively, and scaled across multiple applications and shared libraries.