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:tsclint: ESLint with@nx/eslint:linttest: Vitest with@nx/vite:testtypecheck: Type checking withtsc --noEmit
TypeScript Configuration#
- Modern ESM configuration with
NodeNextmodule 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
exportsfield 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#
-
Install dependencies:
bashpnpm install -
Implement your library: Edit
src/<name>.tswith your actual implementation. -
Add tests: Update
src/<name>.test.tswith comprehensive tests. -
Build and verify:
bashnx build @iris/<name> nx test @iris/<name> nx lint @iris/<name> -
Use in other libraries:
typescriptimport { MyClass } from '@iris/<name>';
Integration with Nx#
The generator automatically:
- Adds path mappings to
tsconfig.base.json - Updates
pnpm-workspace.yamlif 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