Stacks Types
Key Paths
- Core types:
storage/framework/core/types/src/
- Generated types:
storage/framework/types/
- ORM globals:
storage/framework/types/orm-globals.d.ts
- Environment:
storage/framework/types/env.d.ts
- Actions:
storage/framework/types/actions.d.ts (generated ActionPath union)
- Model traits:
storage/framework/types/traits.d.ts
- Model attributes:
storage/framework/types/attributes.d.ts
- Events:
storage/framework/types/events.ts
- Attributes:
storage/framework/types/attributes.ts
Authentication Types (auth.ts)
interface AuthConfig {
default: string
guards: { [key: string]: { driver: 'session' | 'token', provider: string } }
providers: { [key: string]: { driver: 'database', table: string } }
username: string
password: string
tokenExpiry: number // 30 days
tokenRotation: number // 7 days
defaultAbilities: string[]
defaultTokenName: string
}
ORM Global Types (orm-globals.d.ts)
// Full database row — model attributes + system fields + FK columns
type ModelRow<T> = { id: number, uuid: string, created_at: string, updated_at: string } & ModelAttributes<T>
// Insertable data — all fields optional
type NewModelData<T> = Partial<ModelAttributes<T>>
// Updateable data — all fields optional
type UpdateModelData<T> = Partial<ModelAttributes<T>>
// Model-aware request — narrows field names to model's attributes
interface RequestInstance<TModel> {
get(key: keyof TModel): any
all(): TModel
validate(): Promise<void>
}
Environment Types (env.d.ts)
// Application
APP_NAME, APP_ENV: 'local' | 'dev' | 'stage' | 'prod', APP_KEY, APP_URL, PORT, DEBUG
// Database
DB_CONNECTION: 'mysql' | 'sqlite' | 'postgres' | 'dynamodb'
DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
// AWS
AWS_ACCOUNT_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION
// Mail
MAIL_MAILER: 'smtp' | 'mailgun' | 'ses' | 'postmark' | 'sendmail' | 'log'
MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_NAME, MAIL_FROM_ADDRESS
// Search
SEARCH_ENGINE_DRIVER: 'meilisearch' | 'algolia' | 'typesense'
MEILISEARCH_HOST, MEILISEARCH_KEY
// Frontend
FRONTEND_APP_ENV: 'development' | 'staging' | 'production', FRONTEND_APP_URL
Event Types (events.ts)
All model CRUD events: model:created, model:updated, model:deleted
- Content: author, post, page
- Core: user, activity, campaign, comment, email-list, notification, social-post, subscription, tag
- Commerce (30+ models): cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more
All payloads are Record<string, any>.
Billing Types (billing.ts)
interface TransactionHistory {
id?, uuid?, name, description?, amount, type, provider_id?, user_id?, paymentmethod_id?, created_at, updated_at?
}
interface PaymentMethod {
id?, uuid?, type, last_four, brand, exp_month, exp_year, is_default?, provider_id?, user_id?
}
interface Product {
id?, uuid?, name, key, unit_price?, status?, image?, provider_id?
}
interface Subscription {
id?, uuid?, type, provider_id, provider_status, provider_type, unit_price?, quantity?, trial_ends_at?, ends_at?, user_id?
}
Attribute Types (attributes.ts)
200+ attribute definitions covering all models:
| Category |
Fields |
| Basic |
name, slug, description, title, subject, content, body |
| Dates |
created_at, updated_at, published_at, scheduled_at, expires_at |
| Commerce |
unit_price, price, amount, tax_amount, discount_amount, total, currency |
| User |
email, password, phone, avatar, author_name, author_email |
| Shipping |
delivery_address, delivery_fee, region, countries |
| Loyalty |
loyalty_points_earned, loyalty_points_redeemed, points_required |
| Analytics |
views, conversions, clicks, reach, likes, shares |
Request Types (traits.d.ts)
Auto-generated per model:
interface PasskeysRequestType extends Request {
get(key: 'id' | 'cred_public_key' | 'user_id' | 'counter' | ...): any
}
interface CommentablesRequestType extends Request {
get(key: 'title' | 'body' | 'status' | 'commentables_id' | ...): any
}
Auto-Imported Globals
Framework Modules
Action, response, route, Router, schema, validate, slug, camelCase, pascalCase, snakeCase, kebabCase, titleCase, path, storage, log, handleError, Auth, register
60+ ORM Models (globally available)
User, Team, Post, Page, Author, Comment, Product, Order, Cart, Customer, Coupon, Category, Tag, Payment, Subscription, Driver, ShippingRate, GiftCard, LicenseKey, Job, FailedJob, Error, Log, Notification, and many more.
stx components
Components under resources/components/ are resolved by the stx plugin and used directly in templates (<Card />) - no import, no global registration step. Editor metadata is generated into storage/framework/core/web-types.json and custom-elements.json by buddy generate:web-types / generate:custom-data. There is no components.d.ts.
Actions Type
type ActionPath = 'Actions/LogAction' | 'Actions/HealthAction' | 'Actions/ExampleAction' | (string & {})
CLI Types (cli.ts)
interface CliOptions {
verbose?: boolean, silent?: boolean, quiet?: boolean
cwd?: string, background?: boolean, timeoutMs?: number, project?: string
}
interface CleanOptions extends CliOptions {}
interface CommitOptions extends CliOptions {}
interface FreshOptions extends CliOptions { dryRun?: boolean }
Gotchas
- Types are auto-generated — many files in
storage/framework/types/ are generated from model definitions
- ORM globals are truly global —
ModelRow<T>, NewModelData<T> available without imports
- RequestInstance is model-aware —
.get() and .all() narrowed to model's fields when typed
- Event payloads are untyped — all
Record<string, any>, not strongly typed per-model
- Env types augment Bun.env —
Bun.env.DB_CONNECTION is typed
- Attributes is a shared type — 200+ fields covering ALL models, not per-model
- Router types auto-generated — 130+ typed route definitions, regenerated when routes change
- Components.d.ts has 150+ entries — globally registered, no imports needed
1---2name: stacks-types-43description: Use when working with TypeScript type definitions in a Stacks application - model types, request types, environment variables, event types, billing types, attribute types, or auto-imported globals. Covers storage/framework/types/ and storage/framework/core/types/src/.4license: MIT5compatibility: Bun >= 1.3.0, TypeScript6allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-types-49---1011# Stacks Types1213## Key Paths14- Core types: `storage/framework/core/types/src/`15- Generated types: `storage/framework/types/`16- ORM globals: `storage/framework/types/orm-globals.d.ts`17- Environment: `storage/framework/types/env.d.ts`18- Actions: `storage/framework/types/actions.d.ts` (generated `ActionPath` union)19- Model traits: `storage/framework/types/traits.d.ts`20- Model attributes: `storage/framework/types/attributes.d.ts`21- Events: `storage/framework/types/events.ts`22- Attributes: `storage/framework/types/attributes.ts`2324## Authentication Types (auth.ts)2526```typescript27interface AuthConfig {28 default: string29 guards: { [key: string]: { driver: 'session' | 'token', provider: string } }30 providers: { [key: string]: { driver: 'database', table: string } }31 username: string32 password: string33 tokenExpiry: number // 30 days34 tokenRotation: number // 7 days35 defaultAbilities: string[]36 defaultTokenName: string37}38```3940## ORM Global Types (orm-globals.d.ts)4142```typescript43// Full database row — model attributes + system fields + FK columns44type ModelRow<T> = { id: number, uuid: string, created_at: string, updated_at: string } & ModelAttributes<T>4546// Insertable data — all fields optional47type NewModelData<T> = Partial<ModelAttributes<T>>4849// Updateable data — all fields optional50type UpdateModelData<T> = Partial<ModelAttributes<T>>5152// Model-aware request — narrows field names to model's attributes53interface RequestInstance<TModel> {54 get(key: keyof TModel): any55 all(): TModel56 validate(): Promise<void>57}58```5960## Environment Types (env.d.ts)6162```typescript63// Application64APP_NAME, APP_ENV: 'local' | 'dev' | 'stage' | 'prod', APP_KEY, APP_URL, PORT, DEBUG6566// Database67DB_CONNECTION: 'mysql' | 'sqlite' | 'postgres' | 'dynamodb'68DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD6970// AWS71AWS_ACCOUNT_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION7273// Mail74MAIL_MAILER: 'smtp' | 'mailgun' | 'ses' | 'postmark' | 'sendmail' | 'log'75MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_NAME, MAIL_FROM_ADDRESS7677// Search78SEARCH_ENGINE_DRIVER: 'meilisearch' | 'algolia' | 'typesense'79MEILISEARCH_HOST, MEILISEARCH_KEY8081// Frontend82FRONTEND_APP_ENV: 'development' | 'staging' | 'production', FRONTEND_APP_URL83```8485## Event Types (events.ts)8687All model CRUD events: `model:created`, `model:updated`, `model:deleted`8889- **Content**: author, post, page90- **Core**: user, activity, campaign, comment, email-list, notification, social-post, subscription, tag91- **Commerce (30+ models)**: cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more9293All payloads are `Record<string, any>`.9495## Billing Types (billing.ts)9697```typescript98interface TransactionHistory {99 id?, uuid?, name, description?, amount, type, provider_id?, user_id?, paymentmethod_id?, created_at, updated_at?100}101102interface PaymentMethod {103 id?, uuid?, type, last_four, brand, exp_month, exp_year, is_default?, provider_id?, user_id?104}105106interface Product {107 id?, uuid?, name, key, unit_price?, status?, image?, provider_id?108}109110interface Subscription {111 id?, uuid?, type, provider_id, provider_status, provider_type, unit_price?, quantity?, trial_ends_at?, ends_at?, user_id?112}113```114115## Attribute Types (attributes.ts)116117200+ attribute definitions covering all models:118119| Category | Fields |120|----------|--------|121| Basic | name, slug, description, title, subject, content, body |122| Dates | created_at, updated_at, published_at, scheduled_at, expires_at |123| Commerce | unit_price, price, amount, tax_amount, discount_amount, total, currency |124| User | email, password, phone, avatar, author_name, author_email |125| Shipping | delivery_address, delivery_fee, region, countries |126| Loyalty | loyalty_points_earned, loyalty_points_redeemed, points_required |127| Analytics | views, conversions, clicks, reach, likes, shares |128129## Request Types (traits.d.ts)130131Auto-generated per model:132133```typescript134interface PasskeysRequestType extends Request {135 get(key: 'id' | 'cred_public_key' | 'user_id' | 'counter' | ...): any136}137138interface CommentablesRequestType extends Request {139 get(key: 'title' | 'body' | 'status' | 'commentables_id' | ...): any140}141```142143## Auto-Imported Globals144145### Framework Modules146`Action`, `response`, `route`, `Router`, `schema`, `validate`, `slug`, `camelCase`, `pascalCase`, `snakeCase`, `kebabCase`, `titleCase`, `path`, `storage`, `log`, `handleError`, `Auth`, `register`147148### 60+ ORM Models (globally available)149User, Team, Post, Page, Author, Comment, Product, Order, Cart, Customer, Coupon, Category, Tag, Payment, Subscription, Driver, ShippingRate, GiftCard, LicenseKey, Job, FailedJob, Error, Log, Notification, and many more.150151### stx components152Components under `resources/components/` are resolved by the stx plugin and used directly in templates (`<Card />`) - no import, no global registration step. Editor metadata is generated into `storage/framework/core/web-types.json` and `custom-elements.json` by `buddy generate:web-types` / `generate:custom-data`. There is no `components.d.ts`.153154### Actions Type155```typescript156type ActionPath = 'Actions/LogAction' | 'Actions/HealthAction' | 'Actions/ExampleAction' | (string & {})157```158159## CLI Types (cli.ts)160161```typescript162interface CliOptions {163 verbose?: boolean, silent?: boolean, quiet?: boolean164 cwd?: string, background?: boolean, timeoutMs?: number, project?: string165}166167interface CleanOptions extends CliOptions {}168interface CommitOptions extends CliOptions {}169interface FreshOptions extends CliOptions { dryRun?: boolean }170```171172## Gotchas173- **Types are auto-generated** — many files in `storage/framework/types/` are generated from model definitions174- **ORM globals are truly global** — `ModelRow<T>`, `NewModelData<T>` available without imports175- **RequestInstance is model-aware** — `.get()` and `.all()` narrowed to model's fields when typed176- **Event payloads are untyped** — all `Record<string, any>`, not strongly typed per-model177- **Env types augment Bun.env** — `Bun.env.DB_CONNECTION` is typed178- **Attributes is a shared type** — 200+ fields covering ALL models, not per-model179- **Router types auto-generated** — 130+ typed route definitions, regenerated when routes change180- **Components.d.ts has 150+ entries** — globally registered, no imports needed