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

my-lib/

my-lib.ts

MyLib

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