Agent Skills: Monorepo Guide

Monorepo Guide

Context Files (Read First)

For structure and conventions, read from Docs/context/:

• Docs/context/repo-structure.md - Monorepo layout
• Docs/context/packages-map.md - Package index and boundaries
• Docs/context/conventions.md - Naming and architecture rules

Quick Reference

Import Patterns

import { useAuth } from "@shared-auth/hooks/useAuth";
import { Button } from "@ui/button";
import { supabase } from "@/integrations/supabase/client";

Dependency Commands

# Add to root (shared)
npm install <pkg> -w root

# Add to specific app
npm install <pkg> -w apps/raamattu-nyt

# Add to package
npm install <pkg> -w packages/shared-auth

# Always commit package-lock.json after changes

Common Commands

npm run dev          # Start dev server (port 5173)
npm run build        # Production build
npm test             # Run tests in apps/raamattu-nyt
npx @biomejs/biome check --write .  # Lint & format

Creating New Packages

1. Create Package Structure

mkdir -p packages/my-package/src

2. Add package.json

{
  "name": "@raamattu-nyt/my-package",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    "./*": "./src/*"
  }
}

3. Create Index Export

// packages/my-package/src/index.ts
export * from './hooks/useMyHook';
export * from './utils/myUtil';

4. Add Path Alias

In apps/raamattu-nyt/vite.config.ts:

resolve: {
  alias: {
    "@my-package": path.resolve(__dirname, "../../packages/my-package/src"),
  }
}

In apps/raamattu-nyt/tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@my-package/*": ["../../packages/my-package/src/*"]
    }
  }
}

5. Use in App

import { useMyHook } from "@my-package/hooks/useMyHook";

Creating New Apps

1. Scaffold App

mkdir -p apps/new-app/src

2. Add Package Dependencies

{
  "name": "new-app",
  "dependencies": {
    "@raamattu-nyt/shared-auth": "*",
    "@raamattu-nyt/ui": "*"
  }
}

3. Configure Vite & TypeScript

Copy and adapt from apps/raamattu-nyt/:

• vite.config.ts - Path aliases
• tsconfig.json - Path mappings

4. Share Supabase Client

Import from shell or create app-specific client pointing to same project.

Package Inventory

| Alias | Package | Purpose | |-------|---------|---------| | @ui | packages/ui | Shared UI primitives (shadcn/ui) | | @shared-auth | packages/shared-auth | Auth hooks (useAuth, useUserRole) | | @shared-voice | packages/shared-voice | TTS/voice playback | | @shared-history | packages/shared-history | History tracking | | @shared-content | packages/shared-content | Shared content utilities | | @shared-errors | packages/shared-errors | Error handling | | @ai | packages/ai | AI utilities | | @shared-i18n | packages/shared-i18n | i18n helpers | | @shared-reel | packages/shared-reel | Reel utilities | | @shared-recording | packages/shared-recording | Audio recording | | @shared-onboarding | packages/shared-onboarding | Onboarding tours | | @shared-practices | packages/shared-practices | Practice/gamification system | | @shared-subscription | packages/shared-subscription | Subscription/premium gating | | @raamattu-nyt/error-logging | packages/error-logging | Error logging | | @raamattu-nyt/ui-rich-editor | packages/ui-rich-editor | Rich text editor | | @raamattu-nyt/reel-creator | packages/reel-creator | Reel creation | | @raamattu-nyt/share | packages/share | Share utilities | | — | packages/cinema-reader | Cinema mode reader | | — | packages/shared-sync | Sync utilities |

New Package Checklist

When adding a new shared package, configure aliases in 3 places (all required):

1. apps/raamattu-nyt/vite.config.ts → resolve.alias

"@my-package": path.resolve(__dirname, "../../packages/my-package/src"),

2. apps/raamattu-nyt/tsconfig.json → compilerOptions.paths

"@my-package": ["../../packages/my-package/src/index.ts"],
"@my-package/*": ["../../packages/my-package/src/*"]

3. packages/my-package/package.json

{
  "name": "@raamattu-nyt/my-package",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": { "./*": "./src/*" }
}

Important: If any of the 3 locations is missing, you'll get Failed to resolve import "@my-package/...". This is the most common monorepo setup issue.

Troubleshooting

"packages not in sync"

npm install  # Regenerate lockfile
git add package-lock.json && git commit

Failed to resolve import (most common)

Missing alias — check all 3 locations:

1. vite.config.ts → resolve.alias
2. tsconfig.json → compilerOptions.paths
3. Package package.json → exports field

Import Resolution Errors

1. Check path alias in vite.config.ts
2. Check paths in tsconfig.json
3. Ensure package has proper exports field

Build Fails with Type Errors

# Check if tsconfig includes all needed files
npx tsc --noEmit

Cross-cutting learnings: See .claude/LEARNINGS.md → "Monorepo/Package Management" section for package resolution patterns.

References

• Context docs: Docs/context/ (authoritative source)
• CI/CD details: See references/ci-cd.md for workflow configuration