@samuelho-dev/monorepo-library-generator

Effect-based monorepo library generator with workspace-agnostic architecture

Generate production-ready TypeScript libraries for Effect-native monorepos with a single command. Supports 5 library types following Effect 3.0+ best practices and works with any monorepo tool (Nx, pnpm, Yarn, Turborepo).

✨ Key Features

🚀 5 Library Types: Contract, Data-Access, Feature, Infrastructure, Provider
🎯 Effect 3.0+: Context.Tag, Layer.scoped, Data.TaggedError, Schema.Class
📦 Workspace Agnostic: Works with Nx, pnpm workspaces, Yarn, Turborepo
🌍 Platform Aware: Generate server/client/edge exports automatically
🔧 TypeScript 5.6+: Strict mode, project references, composite builds
🧪 Testing Ready: Vitest + @effect/vitest integration
🛡️ Resource Safe: Layer.scoped pattern prevents resource leaks
📚 Self-Documenting: Comprehensive inline docs and CLAUDE.md files
🏗️ Best Practices: Follows Effect-TS patterns and modern monorepo conventions
🌳 Bundle Optimized: Tree-shakeable exports with granular subpath patterns for contract libraries

📦 Installation

As Standalone CLI

# Run directly with npx (no installation required)
npx @samuelho-dev/monorepo-library-generator contract product

# Or install globally
npm install -g @samuelho-dev/monorepo-library-generator
mlg contract product

As Nx Generator (in Nx workspace)

# Install as dev dependency
npm install -D @samuelho-dev/monorepo-library-generator

# Use with nx generate
npx nx g @samuelho-dev/monorepo-library-generator:contract product

🚀 Quick Start

Generate a Contract Library

# Generate with multiple entities (bundle-optimized)
mlg contract product --entities Product,ProductCategory,ProductReview

# Or generate with CQRS and RPC patterns
mlg contract product --includeCQRS --includeRPC

Creates:

Domain entities with Effect Schema (separate files for tree-shaking)
Repository interfaces (ports) with Context.Tag
Domain errors with Data.TaggedError
Domain events
Type-only exports for zero-bundle-impact imports
Optional: CQRS commands/queries
Optional: RPC endpoint definitions

Bundle Optimization: Contract libraries use separate entity files with granular package.json exports:

import { Product } from '@repo/contract-product/entities/product' - Tree-shakeable
import type { Product } from '@repo/contract-product/types' - Zero runtime overhead
import { Product } from '@repo/contract-product' - Convenience (all entities)

Purpose: Define domain boundaries and interfaces (dependency inversion)

Generate a Data-Access Library

mlg data-access product

Creates:

Repository implementation (fulfills contract ports)
Kysely query builders
Data transformations and validation
Layer compositions (Live, Test, Dev, Auto)
Comprehensive tests with @effect/vitest

Purpose: Database operations and persistence layer

Generate a Feature Library

mlg feature user-management --platform universal --includeRPC

Creates:

Business logic service with Context.Tag
Server-side service implementation
Client-side React hooks (if platform includes client)
Edge runtime middleware (if platform includes edge)
Layer compositions with dependency injection
Optional: RPC router definitions

Purpose: Application features and business logic orchestration

Generate an Infrastructure Library

mlg infra cache --platform node

Creates:

Service interface with Context.Tag
Multiple provider implementations (Memory, Redis, etc.)
Type-safe configuration with Effect Config
Server/client/edge layers (platform-dependent)
Error types and validation

Purpose: Cross-cutting technical services (caching, logging, storage)

Generate a Provider Library

mlg provider stripe --externalService stripe --platform node

Creates:

Effect-based service wrapper with Context.Tag
Safe error mapping from SDK errors
Layer implementations (Live, Test, Dev, Auto) with proper cleanup
Type-safe request/response types
Platform-specific exports (server/client/edge)

Purpose: External service integration with consistent Effect interfaces

📚 Library Types & Patterns

1. Contract Libraries (`contract-*`)

Purpose: Domain boundaries through interfaces and types

Key Patterns:

✅ Interface-before-implementation (dependency inversion)
✅ Effect Schema for entities
✅ Data.TaggedError for domain errors
✅ Context.Tag for repository interfaces
✅ Platform-agnostic (universal exports only)

Generated Structure:

libs/contract/{domain}/
├── src/
│   ├── index.ts              # Universal exports
│   └── lib/
│       ├── entities.ts       # Schema.Class entities
│       ├── errors.ts         # Data.TaggedError types
│       ├── events.ts         # Domain events
│       ├── ports.ts          # Repository interfaces (Context.Tag)
│       ├── commands.ts       # CQRS commands (optional)
│       ├── queries.ts        # CQRS queries (optional)
│       └── rpc.ts            # RPC definitions (optional)
├── package.json
├── tsconfig.json
├── tsconfig.lib.json
├── tsconfig.spec.json
├── README.md
└── CLAUDE.md                 # AI agent reference

Dependencies: None (pure domain)

Used By: data-access, feature

Learn More: docs/CONTRACT.md

2. Data-Access Libraries (`data-access-*`)

Purpose: Repository pattern implementation with database operations

Key Patterns:

✅ Implements contract repository interfaces
✅ Kysely query builders for type-safe SQL
✅ Layer.scoped for connection management
✅ Effect.acquireRelease for transaction handling
✅ Repository errors with Data.TaggedError

Generated Structure:

libs/data-access/{domain}/
├── src/
│   ├── index.ts              # Universal exports
│   └── lib/
│       ├── shared/
│       │   ├── errors.ts     # Repository errors
│       │   ├── types.ts      # Filter types, pagination
│       │   └── validation.ts # Input validation
│       ├── repository.ts     # Repository implementation
│       ├── queries.ts        # Kysely query builders
│       └── server/
│           └── layers.ts     # Layer compositions
├── package.json
└── ...

Dependencies:

contract-{domain} (implements interfaces)
infra-database (database service)
provider-kysely (query builder)

Used By: feature

Learn More: docs/DATA-ACCESS.md

3. Feature Libraries (`feature-*`)

Purpose: Business logic and application feature orchestration

Key Patterns:

✅ Service pattern with Context.Tag
✅ Layer composition for dependency injection
✅ Platform-aware exports (server/client/edge)
✅ React hooks for client-side integration
✅ Edge middleware for CDN edge runtime

Generated Structure:

libs/feature/{name}/
├── src/
│   ├── index.ts              # Universal exports
│   ├── server.ts             # Server-side exports (Node.js)
│   ├── client.ts             # Client-side exports (browser)
│   ├── edge.ts               # Edge runtime exports (Vercel/Cloudflare)
│   └── lib/
│       ├── shared/
│       │   ├── errors.ts     # Feature errors
│       │   ├── types.ts      # Shared types
│       │   └── schemas.ts    # Validation schemas
│       ├── server/
│       │   ├── service.ts    # Business logic (Context.Tag)
│       │   ├── layers.ts     # Layer compositions
│       │   └── service.spec.ts
│       ├── client/           # React integration (if platform includes browser)
│       │   ├── hooks/
│       │   ├── atoms/        # Jotai state
│       │   └── components/
│       ├── rpc/              # RPC endpoints (optional)
│       │   ├── rpc.ts
│       │   └── handlers.ts
│       └── edge/             # Edge middleware (if platform includes edge)
│           └── middleware.ts
├── package.json
└── ...

Dependencies:

data-access-{domain} (repositories)
contract-{domain} (domain types)
infra-* (logging, caching, etc.)
provider-* (external services)

Used By: apps (web, api, edge functions)

Learn More: docs/FEATURE.md

4. Infrastructure Libraries (`infra-*`)

Purpose: Cross-cutting technical services and resource management

Key Patterns:

✅ Service interface with Context.Tag
✅ Multiple provider implementations
✅ Layer.scoped for resource cleanup
✅ Effect Config for type-safe configuration
✅ Platform-specific layers (server/client/edge)

Generated Structure:

libs/infra/{concern}/
├── src/
│   ├── index.ts              # Universal exports
│   ├── server.ts             # Server-side exports
│   ├── client.ts             # Client-side exports (if applicable)
│   ├── edge.ts               # Edge exports (if applicable)
│   └── lib/
│       ├── service/
│       │   ├── interface.ts  # Service interface (Context.Tag)
│       │   ├── errors.ts     # Service errors
│       │   └── config.ts     # Effect Config
│       ├── providers/
│       │   ├── memory.ts     # In-memory implementation
│       │   ├── redis.ts      # Redis implementation (example)
│       │   └── ...
│       └── layers/
│           ├── server-layers.ts
│           ├── client-layers.ts
│           └── edge-layers.ts
├── package.json
└── ...

Common Examples:

infra-database - Database connection management
infra-cache - Caching (Redis, Memory)
infra-storage - File storage (S3, Supabase)
infra-logging - Structured logging
infra-queue - Job queues

Dependencies: provider-* (external service adapters)

Used By: data-access, feature, apps

Learn More: docs/INFRA.md

5. Provider Libraries (`provider-*`)

Purpose: Wrap external SDKs with consistent Effect interfaces

Key Patterns:

✅ Effect-based service wrapper (Context.Tag)
✅ Safe error mapping from SDK errors to Effect errors
✅ Layer.scoped with Effect.addFinalizer for cleanup
✅ Mock factories for testing
✅ Platform-specific exports

Generated Structure:

libs/provider/{service}/
├── src/
│   ├── index.ts              # Universal exports
│   ├── server.ts             # Server-side exports
│   ├── client.ts             # Client-side exports (if applicable)
│   ├── edge.ts               # Edge exports (if applicable)
│   └── lib/
│       ├── service.ts        # Service implementation (Context.Tag)
│       ├── errors.ts         # Mapped SDK errors
│       ├── types.ts          # Request/response types
│       ├── validation.ts     # Input validation
│       ├── layers.ts         # Layer.scoped implementations
│       └── service.spec.ts
├── package.json
└── ...

Common Examples:

provider-stripe - Stripe payments API
provider-supabase - Supabase client
provider-kysely - Kysely query builder
provider-redis - Redis client
provider-sentry - Sentry error tracking

Dependencies: External SDKs (stripe, @supabase/supabase-js, etc.)

Used By: infra, feature

Learn More: docs/PROVIDER.md

🎯 Key Patterns & Best Practices

Effect 3.0+ Patterns

Context.Tag for Dependency Injection

// Service definition
export class UserService extends Context.Tag("UserService")<
  UserService,
  {
    readonly findById: (id: string) => Effect.Effect<User, UserNotFoundError>
    readonly create: (data: CreateUserData) => Effect.Effect<User, ValidationError>
  }
>() {}

// Usage
const program = Effect.gen(function* () {
  const userService = yield* UserService
  const user = yield* userService.findById("123")
  return user
})

Layer.scoped for Resource Management

// ✅ CORRECT: Layer.scoped with cleanup
export const RedisServiceLive = Layer.scoped(
  RedisService,
  Effect.gen(function* () {
    const client = yield* Effect.sync(() => createRedisClient(config))

    // Register cleanup function
    yield* Effect.addFinalizer(() =>
      Effect.sync(() => {
        client.disconnect()
        console.log("[Redis] Connection closed")
      })
    )

    return RedisService.make(client)
  })
)

// ❌ WRONG: Layer.sync without cleanup (causes resource leaks)
export const RedisServiceWrong = Layer.sync(RedisService, () => {
  const client = createRedisClient(config)
  return RedisService.make(client)
  // Client never disconnected! Memory leak!
})

Data.TaggedError for Type-Safe Errors

export class UserNotFoundError extends Data.TaggedError("UserNotFoundError")<{
  readonly message: string
  readonly userId: string
}> {
  static create(userId: string) {
    return new UserNotFoundError({
      message: `User not found: ${userId}`,
      userId
    })
  }
}

Platform-Aware Exports

The generator creates platform-specific export files based on your platform setting:

// Universal libraries (contract, util)
import { User } from '@myorg/contract-user'

// Node.js/Server-side (feature, infra, provider with platform: node)
import { UserService } from '@myorg/feature-user/server'
import { DatabaseService } from '@myorg/infra-database/server'
import { StripeService } from '@myorg/provider-stripe/server'

// Browser/Client-side (feature with platform: universal)
import { useUser } from '@myorg/feature-user/client'
import { userAtoms } from '@myorg/feature-user/client'

// Edge Runtime (feature with platform: edge)
import { authMiddleware } from '@myorg/feature-auth/edge'

Workspace-Agnostic Architecture

The generator works with any monorepo tool:

Nx Workspaces: Full integration with project graph and references
pnpm Workspaces: Uses workspace protocol and package.json exports
Yarn Workspaces: Compatible with Yarn workspace patterns
Turborepo: Works with Turborepo's task orchestration

The generator automatically detects your workspace type and adapts:

Extracts package scope from root package.json
Computes TypeScript project references (with graceful fallback for non-Nx)
Uses pnpm workspace protocol for dependencies

🔧 CLI Options

Contract Generator

mlg contract <name> [options]

Options:
  --description <desc>    Library description
  --includeCQRS          Include CQRS patterns (commands, queries, projections)
  --includeRPC           Include RPC endpoint definitions
  --directory <dir>      Custom parent directory
  --tags <tags>          Comma-separated tags

Data-Access Generator

mlg data-access <name> [options]

Options:
  --description <desc>    Library description
  --directory <dir>      Custom parent directory
  --tags <tags>          Comma-separated tags

Feature Generator

mlg feature <name> [options]

Options:
  --description <desc>    Library description
  --platform <platform>   Platform target: node | browser | universal | edge
  --includeClientServer  Generate both client and server exports
  --includeRPC           Include RPC router
  --includeCQRS          Include CQRS structure
  --includeEdge          Include edge runtime support
  --directory <dir>      Custom parent directory
  --tags <tags>          Comma-separated tags

Infrastructure Generator

mlg infra <name> [options]

Options:
  --description <desc>    Library description
  --platform <platform>   Platform target: node | browser | universal | edge
  --includeClientServer  Generate both client and server exports
  --includeEdge          Include edge runtime support
  --directory <dir>      Custom parent directory
  --tags <tags>          Comma-separated tags

Provider Generator

mlg provider <name> --externalService <service> [options]

Options:
  --externalService <service>  External service name (required)
  --description <desc>         Library description
  --platform <platform>        Platform target: node | browser | universal | edge
  --includeClientServer       Generate both client and server exports
  --directory <dir>           Custom parent directory
  --tags <tags>               Comma-separated tags

📋 Requirements

Node.js 18+ (20+ recommended)
TypeScript 5.6+
Effect 3.0+
Monorepo Tool: Nx, pnpm workspaces, Yarn workspaces, or Turborepo

🏗️ Architecture Highlights

Recent Improvements (v1.2.3+)

✅ ~700+ lines of duplication eliminated through shared utilities
✅ Layer.scoped pattern prevents resource leaks in providers
✅ Platform exports (server/client/edge) for all library types
✅ Workspace-agnostic architecture supports any monorepo tool
✅ Dynamic scope detection from workspace root package.json
✅ Unified wrapper pattern across all 5 generators
✅ Shared infrastructure generator consolidates file generation
✅ TypeScript project references with graceful non-Nx fallback

Generated Files

All libraries include:

package.json with proper exports configuration
tsconfig.json extending workspace base
tsconfig.lib.json for library compilation (composite mode)
tsconfig.spec.json for test compilation
README.md with library-specific documentation
CLAUDE.md for AI agent reference
Comprehensive inline documentation

📖 Documentation

Core Documentation

Architecture Overview - System architecture and design
Effect Patterns - Effect-TS patterns and standardized layers ✨ UPDATED
Export Patterns - Platform export conventions
Contract Libraries - Contract generator guide
Examples - End-to-end examples ✨ UPDATED

Implementation & Migration (v2.0)

Implementation Complete - Effect layer standardization summary ✨ NEW
Migration Guide - Upgrade guide for naming changes ✨ NEW
Layer Naming Standards - Official naming conventions ✨ UPDATED
Data-Access Libraries - Data-access generator guide
Feature Libraries - Feature generator guide
Infrastructure Libraries - Infrastructure generator guide
Provider Libraries - Provider generator guide
Nx Standards - Workspace conventions

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/samuelho-dev/monorepo-library-generator
cd monorepo-library-generator
pnpm install
pnpm test

📝 License

🔗 Links

Made with Effect ⚡️ | Workspace Agnostic 🌍 | Type Safe 🛡️

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.changeset		.changeset
.github		.github
.nx/workspace-data		.nx/workspace-data
.vscode		.vscode
docs		docs
patches		patches
scripts		scripts
src.backup		src.backup
src		src
.envrc		.envrc
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
flake.lock		flake.lock
flake.nix		flake.nix
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
setupTests.ts		setupTests.ts
tsconfig.base.json		tsconfig.base.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
tsconfig.spec.json		tsconfig.spec.json
tsconfig.src.json		tsconfig.src.json
tsconfig.test.json		tsconfig.test.json
vitest.config.ci.ts		vitest.config.ci.ts
vitest.config.local.ts		vitest.config.local.ts
vitest.config.ts		vitest.config.ts

License

samuelho-dev/monorepo-library-generator

Folders and files

Latest commit

History

Repository files navigation

@samuelho-dev/monorepo-library-generator

✨ Key Features

📦 Installation

As Standalone CLI

As Nx Generator (in Nx workspace)

🚀 Quick Start

Generate a Contract Library

Generate a Data-Access Library

Generate a Feature Library

Generate an Infrastructure Library

Generate a Provider Library

📚 Library Types & Patterns

1. Contract Libraries (contract-*)

2. Data-Access Libraries (data-access-*)

3. Feature Libraries (feature-*)

4. Infrastructure Libraries (infra-*)

5. Provider Libraries (provider-*)

🎯 Key Patterns & Best Practices

Effect 3.0+ Patterns

Context.Tag for Dependency Injection

Layer.scoped for Resource Management

Data.TaggedError for Type-Safe Errors

Platform-Aware Exports

Workspace-Agnostic Architecture

🔧 CLI Options

Contract Generator

Data-Access Generator

Feature Generator

Infrastructure Generator

Provider Generator

📋 Requirements

🏗️ Architecture Highlights

Recent Improvements (v1.2.3+)

Generated Files

📖 Documentation

Core Documentation

Implementation & Migration (v2.0)

🤝 Contributing

Development Setup

📝 License

🔗 Links

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Contributors 2

Uh oh!

Languages

1. Contract Libraries (`contract-*`)

2. Data-Access Libraries (`data-access-*`)

3. Feature Libraries (`feature-*`)

4. Infrastructure Libraries (`infra-*`)

5. Provider Libraries (`provider-*`)

Packages