---

name: kubit-designing-api description: Use when adding new API surface, modifying existing APIs, or defining TypeScript types for framework features. Use when discussing method signatures, return types, decorator APIs, or module exports.

Designing Kubit APIs

Overview

Design APIs by starting with ideal usage in skeleton/, then codifying as types in packages/core/, then documenting in SPEC.md.

When to Use

• Adding new method, decorator, or export to framework
• Modifying existing API signatures
• Defining types in packages/core/*.d.ts
• User asks "how should this API look?"

API Design Flow

Copydigraph api_flow {
  "Write usage in skeleton/" -> "Add types to packages/core/" -> "Document in SPEC.md" -> "Verify tsc passes";
}

1. Usage First: Write the ideal developer experience in skeleton/
2. Types Second: Add ambient types to make it compile
3. Spec Third: Document with TypeScript signatures
4. Verify: Run tsc --noEmit in skeleton/

Design Principles

Patterns in Use

Decorators: @column(), @before(), @property(), @use() - metadata on classes/properties

Method Chaining: router.get('/').name('home') - fluent API for configuration

Controller Tuples: [Controller, 'method'] - type-safe handler references

Lazy Relations: @hasMany(() => Post) - arrow function to avoid circular deps

Static Dispatch: Job.dispatch({}), Mailable.send({}) - class-level entry points

Type Definition Location

All public types go in packages/core/:

Checklist Before Adding API

• Usage example exists in skeleton/
• Types added to packages/core/
• tsc --noEmit passes in skeleton/
• SPEC.md updated with TypeScript signature
• Follows existing patterns (decorators, chaining, etc.)