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#
-
Create a new package
bashmkdir -p packages/my-package/src cd packages/my-package npm init -
Add package to workspaces (automatic with
packages/*glob) -
Configure TypeScript
json{ "extends": "@lilith/tsconfig/library", "compilerOptions": { "outDir": "./dist", "rootDir": "./src" } } -
Add to project references Update
tsconfig.build.jsonto include the new package. -
Install and link
bashnpm 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 |