kubit-expanding-skeleton
Use when adding new files, patterns, or examples to skeleton/. Use when creating new controller, model, job, mailable, migration, view, or component in the skeleton app.
When & Why to Use This Skill
The kubit-expanding-skeleton skill is a specialized developer tool designed to automate and standardize the expansion of the Kubit framework's skeleton application. It streamlines the creation of core MVC components—including controllers, models, jobs, mailables, migrations, and React-based views—ensuring that all new files strictly adhere to TypeScript conventions, decorator usage, and internal architectural patterns. By providing a structured way to add new features and examples, it helps maintain a clean, compilable, and consistent codebase within the Kubit ecosystem.
Use Cases
- Rapidly scaffolding new backend features by generating class-based controllers and ORM models with predefined decorators and type-safe imports.
- Implementing background processing and notification systems by creating standardized Job and Mailable classes that extend the core framework functionality.
- Managing database schema evolution through the generation of migration classes that follow the project's specific schema and table naming conventions.
- Building consistent frontend interfaces by generating React functional components and SSR views that integrate with the Kubit router and Inertia.js.
- Expanding the framework's reference implementation (skeleton) to demonstrate new patterns, framework features, or architectural conventions to other team members.
| name | kubit-expanding-skeleton |
|---|---|
| description | Use when adding new files, patterns, or examples to skeleton/. Use when creating new controller, model, job, mailable, migration, view, or component in the skeleton app. |
Expanding the Kubit Skeleton
Overview
The skeleton/ directory is the ideal Kubit app. Add patterns here first, then add types to make them compile.
When to Use
- Adding new file to skeleton/ (controller, model, etc.)
- Adding new pattern or convention
- Demonstrating new framework feature
- User asks to show how something would work
Directory Structure
skeleton/
├── app/
│ ├── routes.ts # Route definitions
│ ├── controllers/ # Class-based controllers
│ ├── models/ # ORM models with decorators
│ ├── jobs/ # Job classes
│ └── mail/ # Mailable classes
├── components/ # Shared React components
├── views/ # React page components (SSR)
├── config/ # Runtime configuration
├── database/migrations/ # Migration classes
├── public/ # Static assets
└── tests/ # Test files
Conventions by File Type
Controllers: Class with async methods, receive HttpContext, return view() or values
export default class FooController {
public async index({ request, response }: HttpContext) {
return view('foo/index', { data });
}
}
Models: Class extending Model with @column decorators
@use(SoftDeletes)
export class Foo extends Model {
@column({ primary: true }) public id: number;
@column() public name: string;
@column.dateTime({ autoCreate: true }) public createdAt: DateTime;
}
Jobs: Class extending Job with @property and handle()
export class FooJob extends Job {
@property() public data: string;
async handle() { /* ... */ }
}
Mailables: Class extending Mailable with view rendering
export class FooMail extends Mailable {
@property() public name: string;
async handle() { return this.view('emails.foo', { name: this.name }); }
}
Migrations: Class extending Migration with up/down
export default class extends Migration {
async up() { return schema.createTable('foos', (t) => { /* ... */ }); }
async down() { return schema.dropTableIfExists('foos'); }
}
Views: React FC with typed props, default export
const Foo: FC<{ data: string }> = ({ data }) => <div>{data}</div>;
export default Foo;
Components: React FC with named export
export const Button: FC<Props> = ({ children }) => <button>{children}</button>;
Import Conventions
| Import | Source |
|---|---|
kubit |
Core: defineConfig, env, use |
kubit:router |
router |
kubit:inertia |
view |
kubit:server |
HttpContext |
kubit:orm |
Model, decorators, relations |
kubit:db |
Migration, schema |
kubit:queue |
Job, property |
kubit:mail |
Mailable |
@app/* |
App-level imports |
Checklist When Adding to Skeleton
- Follows existing conventions (class-based, decorators)
- Uses correct import paths
- Types exist in packages/core/ (add if needed)
-
tsc --noEmitpasses - Update SKELETON_APP.md if structure changes