---

name: creating-libraries description: This skill should be used when the user asks to "create a library", "scaffold a new lib", "add a local library", "create a namespace module", "set up _.ts and .ts", or needs to create a new TypeScript library following the _.ts/.ts namespace pattern. Handles both simple (single file) and complex (barrel) library structures.

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:

Copysrc/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:

Copysrc/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

Copy// 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

Copy// 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

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

TSConfig Paths Entry

Copy{
  "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