stacks-types

name	stacks-types
description	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/.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

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
:  |  | , 

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