Monorepo Architecture (Turborepo & Bun)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The web-projects repository is a monorepo designed to manage multiple web applications, shared libraries, and experimental playgrounds within a single unified codebase. It utilizes Bun as the primary package manager and runtime environment, alongside Turborepo for high-performance task orchestration and build caching.
This architecture enables seamless code sharing between frontend applications and internal packages while maintaining strict quality standards through centralized linting, formatting, and type-checking. The monorepo supports a polyglot environment, primarily focusing on TypeScript but also incorporating Rust for high-performance CLI tools.
Sources: AGENTS.md:23-25, CLAUDE.md:23-25, package.json:28-36
Workspace Structure
The repository is organized into three primary workspace directories, as defined in the root package.json. This separation ensures a clear distinction between user-facing applications, reusable logic, and development environments.
Workspace Categories
| Category | Path | Description |
|---|---|---|
| Apps | apps/* | High-level applications (e.g., dotori-note, noumenon-front). |
| Packages | packages/* | Reusable libraries and internal utilities (e.g., ui-craft, shadcn-ui). |
| Playgrounds | playgrounds/* | Local development environments for testing components or CLI tools. |
Sources: package.json:37-43, README.md:9-45
Dependency Visualization
The following diagram illustrates the typical relationship and data flow between the different workspace layers within the monorepo.
The diagram shows how applications and playgrounds consume shared packages, which in turn depend on core configuration packages like typescript-config.
Sources: apps/dotori-note/package.json:18-19, packages/ui-craft/package.json:14, playgrounds/ui-craft-playground/package.json:19-20
Task Orchestration with Turborepo
Turborepo serves as the engine for executing scripts across the workspace. It manages task dependencies and utilizes local and remote caching to prevent redundant work.
Pipeline Configuration
The turbo.json file defines the execution graph for the project's lifecycle. Key tasks such as build and test are configured to respect their internal dependencies (indicated by the ^ prefix).
| Task | Configuration | Purpose |
|---|---|---|
build | outputs: ["dist/**", ".next/**"] | Compiles packages and apps. Depends on dependencies' builds. |
check-types | dependsOn: ["^build"] | Runs TypeScript verification after builds. |
test | dependsOn: ["^build"] | Executes unit and integration tests. |
dev | cache: false, persistent: true | Starts development servers with persistent watchers. |
Sources: turbo.json:4-31
Execution Flow
The following sequence diagram represents how a top-level command like bun build is processed by Turborepo to orchestrate multi-package builds.
Sources: turbo.json:14-18, AGENTS.md:79-84
Package Management with Bun
The project uses Bun (v1.3.4) as the exclusive package manager. This choice impacts how workspace dependencies are resolved and how tasks are executed.
Internal Referencing
Internal packages are linked using the workspace:* protocol. This ensures that the monorepo always uses the local version of a package during development rather than fetching a version from a remote registry.
{
"dependencies": {
"@siluat/ui-craft": "workspace:*",
"@siluat/shadcn-ui": "workspace:*"
}
}
Sources: AGENTS.md:65-68, apps/dotori-note/package.json:18-19
Shared Configuration
TypeScript settings are centralized in @siluat/typescript-config. Individual packages extend these base configurations to ensure consistency in type-checking across the repository.
Sources: AGENTS.md:39-40, packages/ui-craft/package.json:14
Tooling and Standards
Code Quality
- Biome: Used for both formatting and linting across the entire repository. It is enforced via
turbo run static-checkand git hooks. - Lefthook: Manages Git hooks, specifically running Biome checks during the pre-commit stage.
- Changesets: Used for managing package versioning and generating changelogs.
Sources: package.json:13-18, AGENTS.md:14-19, CLAUDE.md:14-19
Development Commands
The root package.json provides convenience scripts that wrap Turborepo commands:
bun dev: Starts all development servers.bun build: Builds all workspace projects.bun test: Runs tests across all packages.bun static-check: Combines type checking and linting.
Sources: package.json:11-20, AGENTS.md:7-12
Summary
The Monorepo Architecture of web-projects leverages the speed of Bun and the efficiency of Turborepo to maintain a scalable, high-quality development environment. By utilizing workspace-aware dependencies and centralized task orchestration, the project ensures that cross-package changes are validated and built in the correct order while maximizing developer productivity through intelligent caching.