@kuckit/sdk

The Kuckit SDK provides the foundation for building modular applications with dependency injection, lifecycle management, and a plugin-style module system.

Features

• DI Container - Awilix-based dependency injection with scoped lifetimes
• Module Loader - Plugin system with lifecycle hooks for registering services and APIs
• Core Services - Pre-configured logger, event bus, cache, rate limiter, and database pool
• Type Safety - Full TypeScript support with typed container resolution

Installation

# Using bun
bun add @kuckit/sdk

# Using npm
npm install @kuckit/sdk

Quick Start

1. Create a Container

import { createKuckitContainer, loadKuckitModules } from '@kuckit/sdk'

const container = await createKuckitContainer({
	config: {
		databaseUrl: process.env.DATABASE_URL!,
		enableFileLogging: false,
		logDir: './logs',
		logLevel: 'INFO',
		env: 'development',
	},
})

2. Load Modules

import { kuckitModule as usersModule } from '@kuckit/users-module'

await loadKuckitModules({
	container,
	env: 'development',
	modules: [
		{ module: usersModule, config: { enableCaching: true } },
		{ package: '@acme/billing-module' }, // npm package
	],
	onApiRegistrations: (registrations) => {
		// Wire API routes to your framework (Express, Hono, etc.)
	},
})

3. Resolve Services

const logger = container.resolve('logger')
const userRepository = container.resolve('userRepository')

logger.info('Application started')

Core Services

After createKuckitContainer(), these services are available:

| Token | Type | Description | | ------------------ | ------------------ | ------------------------------ | | config | CoreConfig | Application configuration | | db | Drizzle instance | Database query builder | | dbPool | Pool | Raw PostgreSQL connection pool | | logger | Logger | Structured logging | | eventBus | EventBus | Pub/sub event system | | clock | Clock | Time abstraction (testable) | | cacheStore | CacheStore | Key-value cache | | rateLimiterStore | RateLimiterStore | Rate limiting | | auth | Auth utilities | Authentication helpers |

Building Modules

See Module Development Guide for a complete guide on creating third-party modules.

import { defineKuckitModule, asClass } from '@kuckit/sdk'

export const kuckitModule = defineKuckitModule({
	id: 'acme.billing',
	displayName: 'Billing',

	register(ctx) {
		ctx.container.register({
			invoiceRepository: asClass(InvoiceRepository).scoped(),
		})
	},
})

API Reference

createKuckitContainer(options)

Creates a DI container with core services registered.

loadKuckitModules(options)

Loads and initializes modules through their lifecycle hooks.

defineKuckitModule(definition)

Type-safe helper to define a module with metadata and hooks.

disposeContainer(container)

Gracefully closes database connections and cleans up resources.

Re-exports

The SDK re-exports useful utilities:

// Awilix helpers
import { asClass, asFunction, asValue } from '@kuckit/sdk'

// Core packages (for advanced use)
import { Domain, Application, Contracts } from '@kuckit/sdk'

License

MIT