Eve library

Lilith Monorepo Structure

Guide

Revision 1

On this page

This document describes the monorepo structure and how to work with the shared packages.

Directory Structure#

text
lilith/
├── packages/           # Shared packages (npm workspaces)
│   ├── core/           # @lilith/core - Types, utilities, constants
│   ├── logger/         # @lilith/logger - Structured logging
│   ├── config/         # @lilith/config - Configuration management
│   ├── errors/         # @lilith/errors - Error types and handling
│   ├── testing/        # @lilith/testing - Test utilities
│   ├── database/       # @lilith/database - PostgreSQL utilities
│   ├── cache/          # @lilith/cache - Redis caching utilities
│   ├── queue/          # @lilith/queue - Job queue utilities
│   ├── metrics/        # @lilith/metrics - Prometheus metrics
│   ├── tracing/        # @lilith/tracing - Distributed tracing
│   ├── eslint-config-lilith/  # Shared ESLint configuration
│   ├── tsconfig-lilith/       # Shared TypeScript configuration
│   └── prettier-config-lilith/ # Shared Prettier configuration
├── services/           # Microservices
│   ├── auth/           # Authentication service
│   ├── bff/            # Backend for Frontend
│   ├── content/        # Content management
│   ├── ai/             # AI orchestration
│   └── ...
├── sdk/                # Client SDKs
│   └── typescript/     # TypeScript SDK
├── web/                # Web application (Next.js)
├── mobile/             # Mobile application (React Native)
└── deploy/             # Deployment configurations

Shared Packages#

Core Packages#

Package Description
@lilith/core Shared types, utilities, and constants
@lilith/logger Structured logging with JSON/pretty output
@lilith/config Environment variable management
@lilith/errors Standardized error classes
@lilith/testing Test mocks, fixtures, and helpers

Infrastructure Packages#

Package Description
@lilith/database PostgreSQL connection pool and utilities
@lilith/cache Redis client and caching utilities
@lilith/queue Job queue implementation
@lilith/metrics Prometheus-compatible metrics
@lilith/tracing OpenTelemetry-compatible tracing

Configuration Packages#

Package Description
@lilith/eslint-config Shared ESLint rules
@lilith/tsconfig Shared TypeScript configuration
@lilith/prettier-config Shared Prettier configuration

Usage#

Installing Dependencies#

bash
# Install all dependencies
npm install

# Install with legacy peer deps (if needed)
npm install --legacy-peer-deps

Building Packages#

bash
# Build all packages with project references
npm run build:packages

# Build with watch mode
npm run build:packages:watch

# Clean build artifacts
npm run clean:packages

Running Tests#

bash
# Run unit tests
npm run test:unit

# Run with watch mode
npm run test:unit:watch

# Run with coverage
npm run test:unit:coverage

# Run E2E tests
npm test

Using Shared Packages in Services#

typescript
// Import from @lilith packages
import { createLogger } from '@lilith/logger';
import { defineConfig, databaseSchema } from '@lilith/config';
import { AppError, NotFoundError } from '@lilith/errors';
import type { User, ApiResponse } from '@lilith/core';

// Create a logger
const logger = createLogger({ service: 'my-service' });

// Load configuration
const config = defineConfig({
  database: databaseSchema,
});

// Use error classes
throw new NotFoundError('User not found', { userId: '123' });

ESLint Configuration#

In your service's .eslintrc.json:

json
{
  "extends": ["@lilith/eslint-config/typescript"]
}

Or for Node.js services:

json
{
  "extends": ["@lilith/eslint-config/node"]
}

TypeScript Configuration#

In your service's tsconfig.json:

json
{
  "extends": "@lilith/tsconfig/node",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"]
}

Prettier Configuration#

In your service's package.json:

json
{
  "prettier": "@lilith/prettier-config"
}

Development Workflow#

  1. Create a new package

    bash
    mkdir -p packages/my-package/src
    cd packages/my-package
    npm init
    
  2. Add package to workspaces (automatic with packages/* glob)

  3. Configure TypeScript

    json
    {
      "extends": "@lilith/tsconfig/library",
      "compilerOptions": {
        "outDir": "./dist",
        "rootDir": "./src"
      }
    }
    
  4. Add to project references Update tsconfig.build.json to include the new package.

  5. Install and link

    bash
    npm install
    

Package Dependencies#

The packages have the following dependency graph:

text
@lilith/core (no deps)
    ↓
@lilith/config (→ core)
@lilith/errors (→ core)
@lilith/logger (→ core)
    ↓
@lilith/testing (→ core, errors)
@lilith/database (→ core, config, errors, logger)
@lilith/cache (→ core, config, errors, logger)
@lilith/queue (→ core, errors, logger)
@lilith/metrics (→ core)
@lilith/tracing (→ core)

Scripts Reference#

Script Description
npm run build:packages Build all packages
npm run build:packages:watch Build packages in watch mode
npm run clean:packages Clean build artifacts
npm run test:unit Run unit tests
npm run test:unit:watch Run tests in watch mode
npm run test:unit:coverage Run tests with coverage
npm run lint:ts Lint TypeScript files
npm run typecheck Type check all files