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)
storage/framework/browser-auto-imports.json defines available imports (200+ entries)
- Types are declared in
storage/framework/types/browser-auto-imports.d.ts
- STX plugin (
bun-plugin-stx) resolves imports at build time
- Available in STX
<script> tags without explicit import statements
Server Context (Routes, Actions, Jobs)
storage/framework/server-auto-imports.json defines server-side imports (100+ entries)
- Types are declared in
storage/framework/types/server-auto-imports.d.ts
- All 60+ ORM models are auto-imported as globals
- 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
- Create function in
resources/functions/:
// resources/functions/myUtils.ts
export function myHelper() { return 'hello' }
- Export from
storage/framework/auto-imports/functions.ts:
export { myHelper } from '../../resources/functions/myUtils'
- Declare types in
storage/framework/auto-imports/globals.d.ts:
declare function myHelper(): string
- 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
1---2name: stacks-auto-imports-23description: 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/.4license: MIT5---67# Stacks Auto-Import System89Automatically makes functions, models, composables, and utilities available globally without explicit imports.1011## Key Paths12- Auto-import functions: `storage/framework/auto-imports/functions.ts`13- Auto-import models: `storage/framework/auto-imports/models.ts`14- Auto-import index: `storage/framework/auto-imports/index.ts`15- Auto-import globals: `storage/framework/auto-imports/globals.ts`16- Global type declarations: `storage/framework/auto-imports/globals.d.ts`17- Browser manifest: `storage/framework/browser-auto-imports.json`18- Server manifest: `storage/framework/server-auto-imports.json`19- Browser type declarations: `storage/framework/types/browser-auto-imports.d.ts` (~80KB)20- Server type declarations: `storage/framework/types/server-auto-imports.d.ts`21- General auto-import types: `storage/framework/types/auto-imports.d.ts`2223## How Auto-Imports Work2425### Browser Context (STX Templates)261. `storage/framework/browser-auto-imports.json` defines available imports (200+ entries)272. Types are declared in `storage/framework/types/browser-auto-imports.d.ts`283. STX plugin (`bun-plugin-stx`) resolves imports at build time294. Available in STX `<script>` tags without explicit `import` statements3031### Server Context (Routes, Actions, Jobs)321. `storage/framework/server-auto-imports.json` defines server-side imports (100+ entries)332. Types are declared in `storage/framework/types/server-auto-imports.d.ts`343. All 60+ ORM models are auto-imported as globals354. Available in any server-side TypeScript file3637### Runtime Injection38`storage/framework/auto-imports/globals.ts` injects functions into `globalThis`:39```typescript40// Makes these available globally without imports:41globalThis.increment = increment42globalThis.count = count43globalThis.isDark = isDark44globalThis.toggleDark = toggleDark45// ... geo functions, GPX functions, etc.46```4748## What Gets Auto-Imported4950### Browser Auto-Imports (200+)51- **Composables**: useStorage, useLocalStorage, useFetch, useToggle, useCounter, useDark, useNow, etc.52- **Utilities**: debounce, throttle, retry, sleep, wait, delay, lazy, clamp, rand53- **Authentication**: useAuth, authGuard, auth54- **Formatting**: formatCurrency, formatDate, formatNumber, formatDuration55- **Browser Query Builder**: browserQuery, BrowserQueryBuilder, browserAuth, createBrowserModel56- **Payment**: confirmCardPayment, confirmPayment, createPaymentMethod, loadCardElement, loadPaymentElement57- **Stripe**: stripe instance58- **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)5960### Server Auto-Imports (100+)61- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (60+ models)62- **Request Models**: UserRequest, PostRequest, OrderRequest, etc.63- **Actions**: Action types and helpers64- **Schema**: validation schema builder65- **Router**: route, response helpers66- **String Utilities**: slug, camelCase, pascalCase, snakeCase, kebabCase, titleCase67- **Core**: path, storage, log, handleError, Auth, register6869## Auto-Import Type Declarations7071### auto-imports.d.ts (general)72```typescript73declare global {74 const Action: typeof import('@stacksjs/actions').Action75 const response: typeof import('@stacksjs/router').response76 const route: typeof import('@stacksjs/router').route77 const schema: typeof import('@stacksjs/validation').schema78 const slug: typeof import('@stacksjs/strings').slug79 // ... all auto-imported identifiers80}81```8283### Adding Custom Auto-Imports84851. Create function in `resources/functions/`:86```typescript87// resources/functions/myUtils.ts88export function myHelper() { return 'hello' }89```90912. Export from `storage/framework/auto-imports/functions.ts`:92```typescript93export { myHelper } from '../../resources/functions/myUtils'94```95963. Declare types in `storage/framework/auto-imports/globals.d.ts`:97```typescript98declare function myHelper(): string99```1001014. Inject at runtime in `storage/framework/auto-imports/globals.ts`:102```typescript103globalThis.myHelper = myHelper104```105106## Generation Commands107108```bash109buddy generate # regenerate all auto-imports110buddy generate --types # regenerate type declarations111buddy generate --ide-helpers # regenerate IDE helpers112buddy generate:component-meta # regenerate component metadata113```114115The `build:reset` script also regenerates auto-imports.116117## Server Auto-Import Initialization118119```typescript120import { initiateImports, generateAutoImportFiles, injectGlobalAutoImports } from '@stacksjs/server'121122initiateImports() // initialize auto-import plugin123generateAutoImportFiles() // generate runtime auto-import files124injectGlobalAutoImports() // inject models/functions globally125```126127## Gotchas128- Browser auto-imports are resolved at BUILD TIME by bun-plugin-stx — not runtime129- Server auto-imports are injected into globalThis at RUNTIME130- The browser-auto-imports.d.ts file is ~80KB — it's auto-generated, don't edit manually131- Custom functions must be exported from both the function file AND the auto-imports barrel132- Type declarations must match the runtime globals for IDE support133- All 60+ ORM models are auto-imported on the server — available as `User.find(1)` etc.134- Request models (e.g., `UserRequest`) are also auto-imported for validated request access135- Auto-imports are regenerated during `buddy generate` and `build:reset`136- The discovered-packages.json file at `storage/framework/discovered-packages.json` is part of this system