Stacks Types

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 (36 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:

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