kubit-designing-api
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.
When & Why to Use This Skill
This Claude skill streamlines the professional design and implementation of APIs within the Kubit framework. It provides a structured, usage-first workflow for adding new API surfaces, defining precise TypeScript types, and ensuring high-quality developer experience (DX) through consistent method signatures and decorator patterns.
Use Cases
- Framework Extension: Use this skill when adding new decorators, methods, or module exports to ensure they align with existing architectural patterns.
- Type Safety Optimization: Define and refine complex TypeScript ambient types in core packages to provide robust compile-time error detection and enhanced IDE intellisense.
- API Refactoring: Modify existing API signatures or return types while maintaining consistency with framework conventions like Laravel/Rails-inspired patterns.
- Documentation & Specification: Update SPEC.md with accurate TypeScript signatures and usage examples following a 'usage-first' design philosophy.
- Architecture Prototyping: Draft ideal developer experiences in skeleton directories to verify API feel before committing to core implementation.
| 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
digraph api_flow {
"Write usage in skeleton/" -> "Add types to packages/core/" -> "Document in SPEC.md" -> "Verify tsc passes";
}
- Usage First: Write the ideal developer experience in skeleton/
- Types Second: Add ambient types to make it compile
- Spec Third: Document with TypeScript signatures
- Verify: Run
tsc --noEmitin skeleton/
Design Principles
| Principle | Application |
|---|---|
| DX First | How does this feel to use? Start from skeleton. |
| Type Safety | Can TypeScript catch mistakes at compile time? |
| Conventions | Follow Laravel/Rails patterns where sensible |
| Minimal API | Smallest surface that solves the problem |
| Extensibility | Can users extend without modifying core? |
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/:
| File | Contents |
|---|---|
kubit.d.ts |
defineConfig, env, use |
router.d.ts |
router object, handler types |
orm.d.ts |
Model, column decorators, relations |
queue.d.ts |
Job, @property |
mail.d.ts |
Mailable |
db.d.ts |
Migration, schema |
inertia.d.ts |
view() |
http.d.ts |
HttpContext |
hash.d.ts |
hash() |
Checklist Before Adding API
- Usage example exists in skeleton/
- Types added to packages/core/
-
tsc --noEmitpasses in skeleton/ - SPEC.md updated with TypeScript signature
- Follows existing patterns (decorators, chaining, etc.)