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