monorepo-guide

name	monorepo-guide
description	Guide for working with the Raamattu Nyt monorepo structure. Use when creating new packages, adding apps, managing workspace dependencies, understanding import patterns, or troubleshooting monorepo issues. Covers npm workspaces, shared packages, cross-app code sharing, and Lovable Cloud deployment.

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
• Domain-specific learnings: See references/learnings.md for bun-pohjaisen monorepo-spesifit gotchat