stacks-auto-imports

name	stacks-auto-imports
description	Use when working with the Stacks auto-import system — understanding how browser and server auto-imports work, configuring auto-imported functions/models/composables, the auto-import manifests, type generation, or how globals are injected. Covers the auto-import pipeline at storage/framework/auto-imports/.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks Auto-Import System

Automatically makes functions, models, composables, and utilities available globally without explicit imports.

Key Paths

• Auto-import functions: storage/framework/auto-imports/functions.ts
• Auto-import models: storage/framework/auto-imports/models.ts
• Auto-import index: storage/framework/auto-imports/index.ts
• Auto-import globals: storage/framework/auto-imports/globals.ts
• Global type declarations: storage/framework/auto-imports/globals.d.ts
• Browser manifest: storage/framework/browser-auto-imports.json
• Server manifest: storage/framework/server-auto-imports.json
• Browser type declarations: storage/framework/types/browser-auto-imports.d.ts (~80KB)
• Server type declarations: storage/framework/types/server-auto-imports.d.ts
• General auto-import types: storage/framework/types/auto-imports.d.ts

How Auto-Imports Work

Browser Context (STX Templates)

1. storage/framework/browser-auto-imports.json defines available imports (200+ entries)
2. Types are declared in storage/framework/types/browser-auto-imports.d.ts
3. STX plugin (bun-plugin-stx) resolves imports at build time
4. Available in STX <script> tags without explicit import statements

Server Context (Routes, Actions, Jobs)

1. storage/framework/server-auto-imports.json defines server-side imports (100+ entries)
2. Types are declared in storage/framework/types/server-auto-imports.d.ts
3. All 60+ ORM models are auto-imported as globals
4. Available in any server-side TypeScript file

Runtime Injection

storage/framework/auto-imports/globals.ts injects functions into globalThis:

// Makes these available globally without imports:
globalThis.increment = increment
globalThis.count = count
globalThis.isDark = isDark
globalThis.toggleDark = toggleDark
// ... geo functions, GPX functions, etc.

What Gets Auto-Imported

Browser Auto-Imports (200+)

• Composables: useStorage, useLocalStorage, useFetch, useToggle, useCounter, useDark, useNow, etc.
• Utilities: debounce, throttle, retry, sleep, wait, delay, lazy, clamp, rand
• Authentication: useAuth, authGuard, auth
• Formatting: formatCurrency, formatDate, formatNumber, formatDuration
• Browser Query Builder: browserQuery, BrowserQueryBuilder, browserAuth, createBrowserModel
• Payment: confirmCardPayment, confirmPayment, createPaymentMethod, loadCardElement, loadPaymentElement
• Stripe: stripe instance
• Custom Functions: From resources/functions/ (counter, dark mode, GPX, geo utilities)

Server Auto-Imports (100+)

• All ORM Models: User, Post, Author, Product, Order, Payment, Customer, etc. (60+ models)
• Request Models: UserRequest, PostRequest, OrderRequest, etc.
• Actions: Action types and helpers
• Schema: validation schema builder
• Router: route, response helpers
• String Utilities: slug, camelCase, pascalCase, snakeCase, kebabCase, titleCase
• Core: path, storage, log, handleError, Auth, register

Auto-Import Type Declarations

auto-imports.d.ts (general)

declare global {
  const Action: typeof import('@stacksjs/actions').Action
  const response: typeof import('@stacksjs/router').response
  const route: typeof import('@stacksjs/router').route
  const schema: typeof import('@stacksjs/validation').schema
  const slug: typeof import('@stacksjs/strings').slug
  // ... all auto-imported identifiers
}

Adding Custom Auto-Imports

1. Create function in resources/functions/:

// resources/functions/myUtils.ts
export function myHelper() { return 'hello' }

2. Export from storage/framework/auto-imports/functions.ts:

export { myHelper } from '../../resources/functions/myUtils'

3. Declare types in storage/framework/auto-imports/globals.d.ts:

declare function myHelper(): string

4. Inject at runtime in storage/framework/auto-imports/globals.ts:

globalThis.myHelper = myHelper

Generation Commands

buddy generate                  # regenerate all auto-imports
buddy generate --types          # regenerate type declarations
buddy generate --ide-helpers    # regenerate IDE helpers
buddy generate:component-meta   # regenerate component metadata

The build:reset script also regenerates auto-imports.

Server Auto-Import Initialization

import { initiateImports, generateAutoImportFiles, injectGlobalAutoImports } from '@stacksjs/server'

initiateImports()              // initialize auto-import plugin
generateAutoImportFiles()      // generate runtime auto-import files
injectGlobalAutoImports()      // inject models/functions globally

Gotchas

• Browser auto-imports are resolved at BUILD TIME by bun-plugin-stx — not runtime
• Server auto-imports are injected into globalThis at RUNTIME
• The browser-auto-imports.d.ts file is ~80KB — it's auto-generated, don't edit manually
• Custom functions must be exported from both the function file AND the auto-imports barrel
• Type declarations must match the runtime globals for IDE support
• All 60+ ORM models are auto-imported on the server — available as User.find(1) etc.
• Request models (e.g., UserRequest) are also auto-imported for validated request access
• Auto-imports are regenerated during buddy generate and build:reset
• The discovered-packages.json file at storage/framework/discovered-packages.json is part of this system