Adding a New Library

libs/
├── shared/              # Cross-domain utilities (any domain can use)
│   ├── utils/           # Common utilities
│   ├── types/           # Shared TypeScript types
│   └── {your-lib}/      # ← Add here for shared utilities
│
├── contracts/           # Cross-domain contracts
│   ├── events/          # Event schemas
│   └── types/           # Shared types
│
└── {domain}/            # Domain-specific libraries
    ├── database/        # Domain database client
    ├── client/          # Domain API client
    └── {your-lib}/      # ← Add here for domain-specific code

# Shared utility library
nx g @nx/js:library my-lib --directory=libs/shared/my-lib --importPath=@oshun/my-lib

# Domain-specific library
nx g @nx/js:library my-lib --directory=libs/isis/my-lib --importPath=@isis/my-lib

libs/shared/my-lib/
├── src/
│   ├── index.ts           # Public API exports
│   ├── my-lib.ts          # Main implementation
│   └── my-lib.spec.ts     # Tests
├── project.json           # Nx project configuration
├── package.json           # Package metadata
├── tsconfig.json          # TypeScript configuration
├── tsconfig.lib.json      # Build configuration
├── tsconfig.spec.json     # Test configuration
└── README.md              # Documentation

{
  "name": "@oshun/my-lib",
  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/shared/my-lib/src",
  "projectType": "library",
  "tags": ["scope:shared", "type:lib", "layer:domain"],
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/shared/my-lib",
        "main": "libs/shared/my-lib/src/index.ts",
        "tsConfig": "libs/shared/my-lib/tsconfig.lib.json",
        "assets": ["libs/shared/my-lib/*.md"]
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "options": {
        "config": "libs/shared/my-lib/vitest.config.ts"
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"]
    },
    "typecheck": {
      "executor": "nx:run-commands",
      "options": {
        "cwd": "libs/shared/my-lib",
        "command": "tsc --noEmit"
      }
    }
  }
}

{
  "name": "@oshun/my-lib",
  "version": "0.1.0",
  "description": "Description of your library",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist", "README.md"],
  "scripts": {
    "build": "tsc -p tsconfig.lib.json",
    "test": "vitest run",
    "lint": "eslint src --ext ts",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    // Add your dependencies here
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vitest": "catalog:"
  },
  "peerDependencies": {
    // Add peer dependencies if needed
  }
}

{
  "extends": "../../../tsconfig.base.json",
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "types": ["vitest/globals"]
  },
  "files": [],
  "include": [],
  "references": [
    { "path": "./tsconfig.lib.json" },
    { "path": "./tsconfig.spec.json" }
  ]
}

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "declaration": true,
    "declarationMap": true,
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
}

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist/test",
    "types": ["vitest/globals"]
  },
  "include": ["src/**/*.spec.ts", "src/**/*.test.ts"]
}

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.{test,spec}.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
    },
  },
});

/**
 * @oshun/my-lib - Description of your library
 *
 * @packageDocumentation
 */

export { MyClass, MyFunction, MyType } from './my-lib';

/**
 * Example interface
 */
export interface MyType {
  id: string;
  name: string;
  value: number;
}

/**
 * Example class
 */
export class MyClass {
  private data: MyType[];

  constructor() {
    this.data = [];
  }

  add(item: MyType): void {
    this.data.push(item);
  }

  get(id: string): MyType | undefined {
    return this.data.find((item) => item.id === id);
  }

  getAll(): MyType[] {
    return [...this.data];
  }
}

/**
 * Example function
 *
 * @param input - The input value
 * @returns The processed output
 */
export function MyFunction(input: string): string {
  return input.toUpperCase();
}

import { describe, it, expect, beforeEach } from 'vitest';
import { MyClass, MyFunction, MyType } from './my-lib';

describe('MyClass', () => {
  let instance: MyClass;

  beforeEach(() => {
    instance = new MyClass();
  });

  describe('add', () => {
    it('should add items', () => {
      const item: MyType = { id: '1', name: 'Test', value: 42 };
      instance.add(item);
      expect(instance.getAll()).toHaveLength(1);
    });
  });

  describe('get', () => {
    it('should retrieve items by id', () => {
      const item: MyType = { id: '1', name: 'Test', value: 42 };
      instance.add(item);
      expect(instance.get('1')).toEqual(item);
    });

    it('should return undefined for non-existent ids', () => {
      expect(instance.get('non-existent')).toBeUndefined();
    });
  });
});

describe('MyFunction', () => {
  it('should convert input to uppercase', () => {
    expect(MyFunction('hello')).toBe('HELLO');
  });

  it('should handle empty strings', () => {
    expect(MyFunction('')).toBe('');
  });
});

{
  "compilerOptions": {
    "paths": {
      "@oshun/my-lib": ["libs/shared/my-lib/src/index.ts"]
      // ... other paths
    }
  }
}

# @oshun/my-lib

Description of your library.

## Installation

This library is part of the Oshun monorepo and is available as a workspace
dependency.

\`\`\`bash pnpm add @oshun/my-lib \`\`\`

## Usage

\`\`\`typescript import { MyClass, MyFunction } from '@oshun/my-lib';

const instance = new MyClass(); instance.add({ id: '1', name: 'Example', value:
100 });

const result = MyFunction('hello'); \`\`\`

## API

### MyClass

- `add(item: MyType): void` - Add an item
- `get(id: string): MyType | undefined` - Get item by ID
- `getAll(): MyType[]` - Get all items

### MyFunction

- `MyFunction(input: string): string` - Convert input to uppercase

# Build the library
nx build @oshun/my-lib

# Run tests
nx test @oshun/my-lib

# Run linting
nx lint @oshun/my-lib

# Type check
nx typecheck @oshun/my-lib

# View in dependency graph
nx graph

✅ @oshun/retry      # Just retry logic
✅ @oshun/cache      # Just caching
✅ @oshun/validation # Just validation

❌ @oshun/utils      # Too broad - split into specific utilities

// index.ts

// ✅ Explicit exports
export { PublicClass } from './public-class';
export type { PublicType } from './types';

// ❌ Don't re-export internal utilities
// export * from './internal-helpers';

{
  "dependencies": {
    // Runtime dependencies required by consumers
    "zod": "catalog:"
  },
  "devDependencies": {
    // Only needed during development/testing
    "vitest": "catalog:"
  },
  "peerDependencies": {
    // Must be provided by consumer
    "typescript": "catalog:"
  }
}

// Test public API thoroughly
describe('PublicFunction', () => {
  // Happy path
  it('should handle valid input', () => {});

  // Edge cases
  it('should handle empty input', () => {});
  it('should handle null/undefined', () => {});

  // Error cases
  it('should throw on invalid input', () => {});
});

/**
 * Performs an operation with retry logic.
 *
 * @param operation - The async operation to retry
 * @param options - Retry configuration options
 * @returns The result of the operation
 * @throws {RetryError} When all retry attempts fail
 *
 * @example
 * ```typescript
 * const result = await retry(
 *   () => fetchData(),
 *   { maxRetries: 3, delay: 1000 }
 * );
 * ```
 */
export async function retry<T>(
  operation: () => Promise<T>,
  options: RetryOptions
): Promise<T> {
  // ...
}