Creating Modules

Creating Modules

Steps

1. Create module directory: packages/<pkg>/​src/<module-name>/

2. Create implementation files: <module-name>.ts or split across multiple files

3. Create barrel file __.ts:

   export * from './​implementation.js'
   export type * from './​types.js'
   

4. Create namespace file _.ts:

   export * as ModuleName from './​__.js'
   

5. Add to package.json imports:

   {
     "imports": {
       "#module-name": "./​build/​module-name/​_.js",
       "#module-name/​*": "./​build/​module-name/​*.js"
     }
   }
   

6. Add to package.json exports:

   {
     "exports": {
       "./​module-name": "./​build/​module-name/​__.js"
     }
   }
   

7. Sync tsconfig paths (run syncing-tsconfig-paths skill script)

8. Add to main exports in src/​index.ts:

   export * from '#module-name'
   

Reference

Module Structure

src/​module-name/
├── _.ts              # Namespace file - exports the namespace
├── _.test.ts         # Module tests
├── __.ts             # Barrel file - exports all functions/​types
└── *.ts              # Implementation files

Import System

Use # imports for internal module references within a package:

// Correct - use # imports
import { Fn } from '#fn'
import { Obj } from '#obj'

// Incorrect - don't use relative or package imports internally
import { Fn } from '../​fn/​_.js'
import { Obj } from '@kitz/​core/​obj'

Naming

• Directory: kebab-case (group-by/)
• Namespace export: PascalCase (GroupBy)
• Functions: camelCase, no namespace prefix (by, not groupBy)

Notes

• Each package defines its own # imports in package.json
• Cross-package # imports are not valid - use package name imports