Monorepo Structure

The Odysee.ai frontend is organized as a Turborepo monorepo, which provides efficient build orchestration, intelligent caching, and workspace management.

Why Monorepo?

Code Sharing: Share components, utilities, and configurations across applications
Atomic Changes: Update multiple packages in a single commit
Consistent Tooling: Unified linting, formatting, and testing
Faster Builds: Turborepo's caching dramatically speeds up builds
Type Safety: End-to-end type safety across all packages

Directory Structure

turbo.json

package.json

pnpm-workspace.yaml

pnpm-lock.yaml

Turborepo Configuration

turbo.json

Defines build pipeline and caching strategy:

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Key Concepts

Task Dependencies (dependsOn):

^build: Run build in dependencies first
Example: ui package builds before web app

Caching:

Turborepo caches task outputs
Reuses cache when inputs haven't changed
Dramatically speeds up builds

Task Execution:

# Run build in all workspaces
pnpm build

# Turborepo executes:
# 1. packages/lib build
# 2. packages/ui build (depends on lib)
# 3. apps/web build (depends on ui and lib)
# 4. apps/storybook build (depends on ui and lib)

Workspace Configuration

pnpm-workspace.yaml

packages:
  - "apps/*"
  - "packages/*"

This tells pnpm to treat all directories in apps/ and packages/ as workspaces.

Dependencies Between Workspaces

Workspaces can depend on each other using workspace:*:

// apps/web/package.json
{
  "dependencies": {
    "@shared/ui": "workspace:*",
    "@shared/lib": "workspace:*"
  }
}

Benefits:

Type safety: Changes in shared packages immediately reflect
No publishing: No need to publish to npm registry
Fast iteration: Edit shared code and see changes instantly

Caching Strategy

Turborepo caches based on:

File contents (git hash)
Task configuration
Environment variables (specified in turbo.json)

Cache hits skip task execution entirely.

Remote Caching

Enable remote caching to speed up builds across your team:

# Login to Vercel
pnpm dlx turbo login

# Link the project
pnpm dlx turbo link

This allows sharing build cache across your team, significantly speeding up CI/CD and local builds.

Adding New Workspaces

Create App Directory

Create apps/new-app/ directory

Add package.json

Add package.json with workspace dependencies

{
  "name": "new-app",
  "dependencies": {
    "@shared/ui": "workspace:*",
    "@shared/lib": "workspace:*"
  }
}

Configure Turborepo

Add build script to turbo.json

Install Dependencies

Run pnpm install

Create Package Directory

Create packages/new-package/ directory

Add package.json

Add package.json with "name": "@shared/new-package"

{
  "name": "@shared/new-package",
  "version": "0.0.0",
  "main": "./index.ts",
  "types": "./index.ts"
}

Create Exports

Create index.ts with exports

Reference in Apps

Add to consuming apps: "@shared/new-package": "workspace:*"

Install Dependencies

Run pnpm install

Next: Learn about the Applications in the monorepo.

On this page