monorepo-guide

Spectaculous-Code's avatarfrom Spectaculous-Code

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[Architecture Design]

When & Why to Use This Skill

This Claude skill serves as a comprehensive technical guide for managing and scaling the Raamattu Nyt monorepo architecture. It streamlines developer workflows by providing standardized procedures for npm workspaces, shared package management, and cross-app dependency synchronization, ensuring structural integrity and efficient code sharing across the entire codebase.

Use Cases

  • Scaffolding new applications or shared packages with correct directory structures and configuration files.
  • Managing complex workspace dependencies and ensuring the package-lock.json remains synchronized across the monorepo.
  • Configuring and troubleshooting TypeScript path aliases and Vite resolve patterns for seamless cross-package imports.
  • Standardizing CI/CD and deployment workflows, specifically for Lovable Cloud and production build environments.
  • Resolving common monorepo bottlenecks such as import resolution errors, type mismatches, and workspace sync issues.
namemonorepo-guide
descriptionGuide 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.

Troubleshooting

"packages not in sync"

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

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

References

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