Creating Libraries

Creating Libraries

Scaffold new TypeScript libraries following the namespace module conventions.

CRITICAL

Read the Conventions First

Before creating any library, read the appropriate convention documents:

• Core pattern: ~/.claude/docs/conventions/namespace-module.md — The abstract _.ts/__.ts pattern
• Local libraries (/src/lib/*): ~/.claude/docs/conventions/library-local.md
• Package libraries (package IS the library): ~/.claude/docs/conventions/library-package.md

File Naming

• _.ts — Namespace module (REQUIRED)
• __.ts — Barrel module (only if multiple implementation files)
• _.test.ts — Public API tests
• _.test.fixture.ts — Shared test fixtures (exports namespace Fx)

Operations

Create Simple Library (Single Implementation)

Use when library has one implementation file.

Structure:

src/lib/<name>/
├── _.ts           # export * as Name from './<name>.js'
├── <name>.ts      # Implementation
└── _.test.ts      # Tests

Steps:

1. Create directory at src/lib/<name>/ (kebab-case)
2. Create <name>.ts with implementation
3. Create _.ts with: export * as <PascalName> from './<name>.js'
4. Create _.test.ts importing from ./_.js
5. Add to package.json imports: "#<name>": "./build/lib/<name>/_.js"
6. Add to tsconfig.json paths: "#<name>": ["src/lib/<name>/_.ts"]

Create Complex Library (Multiple Files)

Use when library has multiple implementation files.

Structure:

src/lib/<name>/
├── _.ts           # export * as Name from './__.js'
├── __.ts          # Barrel: exports from all implementation files
├── foo.ts         # Implementation
├── bar.ts         # Implementation
└── _.test.ts      # Tests

Steps:

1. Create directory at src/lib/<name>/ (kebab-case)
2. Create implementation files
3. Create __.ts with re-exports from all implementation files
4. Create _.ts with: export * as <PascalName> from './__.js'
5. Create _.test.ts importing from ./_.js
6. Add package.json imports and tsconfig.json paths

Examples

Simple Library Example

// src/lib/mask/mask.ts
export const create = (pattern: string): Mask => ({ pattern })
export const apply = (mask: Mask, value: string): string => value
export interface Mask {
  pattern: string
}

// src/lib/mask/_.ts
export * as Mask from './mask.js'

// src/lib/mask/_.test.ts
import { Mask } from './_.js'
test('.create', () => {/* ... */})

Complex Library Example

// src/lib/parser/tokenizer.ts
export const tokenize = (input: string): Token[] => []

// src/lib/parser/lexer.ts
export const lex = (tokens: Token[]): Lexeme[] => []

// src/lib/parser/__.ts
export { lex, type Lexeme } from './lexer.js'
export { type Token, tokenize } from './tokenizer.js'

// src/lib/parser/_.ts
export * as Parser from './__.js'

Reference

Naming Conventions

Package.json Imports Entry

{
  "imports": {
    "#<name>": "./build/lib/<name>/_.js"
  }
}

TSConfig Paths Entry

{
  "compilerOptions": {
    "paths": {
      "#<name>": ["src/lib/<name>/_.ts"]
    }
  }
}

Notes

• Always use .js extension in imports (ESM requirement)
• Namespace name = PascalCase of directory name
• Tests import ONLY from _.ts, never from implementation files
• Code modules can import siblings via relative paths
• Cross-library imports use #<name> subpath imports