Eve library

Iris Library Generator

Other

Revision 1

On this page

Generate a new TypeScript library for the Iris AI Assistant platform with a standardized structure.

Usage#

Basic Usage#

bash
# Using Nx generate
nx generate @oshun/tools:iris-library --name=my-lib --description="My awesome library"

# Short form
nx g @oshun/tools:iris-library my-lib

With Options#

bash
nx generate @oshun/tools:iris-library \
  --name=memory-manager \
  --description="Advanced memory management for Iris" \
  --layer=core \
  --dependencies=types,core \
  --withTests=true

Options#

Option Type Default Description
name string (required) The name of the library (e.g., 'memory', 'agent')
description string (required) A short description of the library's purpose
layer string 'domain' Architectural layer: core, domain, infra, api, testing
directory string 'libs/iris' Parent directory for the library
importPath string @iris/<name> Custom import path
dependencies array [] List of Iris library dependencies (e.g., ['types'])
withTests boolean true Generate test files and vitest configuration
withExports boolean true Generate sample exports in index.ts

Generated Structure#

text
libs/iris/<name>/
├── src/
│   ├── index.ts           # Main exports
│   ├── <name>.ts          # Main module with types and classes
│   └── <name>.test.ts     # Unit tests
├── project.json           # Nx project configuration
├── package.json           # Package configuration (ESM)
├── tsconfig.json          # TypeScript base config
├── tsconfig.lib.json      # Library compilation config
├── tsconfig.spec.json     # Test compilation config
├── vitest.config.ts       # Vitest configuration
└── README.md              # Documentation

Features#

Project Configuration#

The generator creates a project.json with:

  • Tags: scope:iris, type:lib, layer:<layer>
  • Targets:
    • build: TypeScript compilation with @nx/js:tsc
    • lint: ESLint with @nx/eslint:lint
    • test: Vitest with @nx/vite:test
    • typecheck: Type checking with tsc --noEmit

TypeScript Configuration#

  • Modern ESM configuration with NodeNext module resolution
  • Strict type checking enabled
  • Separate configs for library and test compilation
  • Project references for optimal incremental builds

Package Configuration#

  • ESM-first with dual exports
  • Proper exports field for submodule imports
  • Catalog dependencies from pnpm workspace
  • Node.js 20+ engine requirement

Testing#

  • Vitest configuration with globals
  • V8 coverage provider
  • HTML and JSON coverage reports
  • Test file patterns: *.test.ts, *.spec.ts

Architectural Layers#

Layer Description Example Libraries
core Core utilities and base abstractions @iris/core, @iris/config
domain Domain-specific business logic @iris/memory, @iris/agent
infra Infrastructure and external adapters @iris/database, @iris/cache
api API contracts and route handlers @iris/api
testing Test utilities and mocks @iris/testing
contracts Shared types and schemas @iris/types, @iris/contracts

Examples#

Create a Core Library#

bash
nx g @oshun/tools:iris-library \
  --name=logger \
  --description="Structured logging for Iris" \
  --layer=core

Create a Domain Library with Dependencies#

bash
nx g @oshun/tools:iris-library \
  --name=conversation \
  --description="Conversation management and dialogue" \
  --layer=domain \
  --dependencies=types,core,memory

Create a Testing Library#

bash
nx g @oshun/tools:iris-library \
  --name=test-utils \
  --description="Testing utilities and mocks" \
  --layer=testing \
  --withTests=false

After Generation#

  1. Install dependencies:

    bash
    pnpm install
    
  2. Implement your library: Edit src/<name>.ts with your actual implementation.

  3. Add tests: Update src/<name>.test.ts with comprehensive tests.

  4. Build and verify:

    bash
    nx build @iris/<name>
    nx test @iris/<name>
    nx lint @iris/<name>
    
  5. Use in other libraries:

    typescript
    import { MyClass } from '@iris/<name>';
    

Integration with Nx#

The generator automatically:

  • Adds path mappings to tsconfig.base.json
  • Updates pnpm-workspace.yaml if needed
  • Creates proper project configuration for Nx graph

You can verify the integration:

bash
# View project graph
nx graph

# Run affected tests
nx affected:test

# Build all Iris libraries
nx run-many --target=build --projects=tag:scope:iris