creating-modules

name	creating-modules
description	Add a namespace/module to a @kitz package — including extending the @kitz/effect namespaces. Covers the _.ts/__.ts barrel pattern, the package exports map, and import conventions.

Creating Modules

A module is a PascalCase namespace inside a package. Two common cases:

• Extend @kitz/effect — add a new namespace (a concept) alongside FileSystem and Path. The lightweight alternative to a whole new package (creating-packages).
• Add a module to any @kitz/* package — the same mechanics anywhere.

Read packages/effect/src/_.ts (the root namespace bundle) and packages/effect/src/path/ (a submodule namespace) as the canonical examples.

Structure

# Single source file (__.ts elided):
src/<module>/
├── _.ts              # root assembly: export * as <Name> from './<module>.js'
├── _.test.ts
└── <module>.ts       # implementation

# Multiple source files:
src/<module>/
├── _.ts              # root assembly: export * as <Name> from './__.js'
├── _.test.ts
├── __.ts             # barrel: export * from './impl.js'
└── *.ts

• Directory: kebab-case. Namespace export: PascalCase. Functions: camelCase, no namespace prefix (by, not groupBy).
• Prefer export * from in barrels; use named re-exports only to rename or exclude.
• Elision: when __.ts would re-export a single file, skip it and have _.ts export the implementation directly.
• _.ts exists only to assemble the namespace exported by the package root. Explicit package subpaths target the module itself: __.ts, or the implementation file when __.ts is elided.

Wire the namespace into the package

1. Re-export from the package root src/_.ts:

   export { <Name> } from './<module>/_.js'
   

2. Add the package.json exports entry — live-types, mirroring the existing entries (dev → src, publish → build):

   // exports
   "./<Name>": "./src/<module>/__.ts",
   // publishConfig.exports
   "./<Name>": "./build/<module>/__.js"
   

3. Verify: pnpm exec vp run check and (if exported) pnpm exec vp run check:package.

Imports

• No # imports. That convention was removed; packages no longer declare an imports map. Within a package, use relative imports (./other/_.js).
• Package root: import assembled namespaces by name — import { FileSystem, Path } from '@kitz/effect'.
• Explicit subpath: import the direct module namespace — import * as Path from '@kitz/effect/Path'.