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
Browser auto-import injection applies to the STX script entry being compiled.
TypeScript modules imported by that script do not inherit its lexical bindings.
Every imported module must explicitly import the functions, stores, and types it
uses. A generated ambient declaration proves an identifier is available to an
STX entry; it does not make that identifier global inside bundled dependencies.
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. (103 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
- Imported browser modules must declare their own imports; STX entry auto-imports do not leak into module scope
- 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-43description: 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: MIT5compatibility: Bun >= 1.3.0, TypeScript6allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-auto-imports-49---1011# Stacks Auto-Import System1213Automatically makes functions, models, composables, and utilities available globally without explicit imports.1415## Key Paths16- Auto-import functions: `storage/framework/auto-imports/functions.ts`17- Auto-import models: `storage/framework/auto-imports/models.ts`18- Auto-import index: `storage/framework/auto-imports/index.ts`19- Auto-import globals: `storage/framework/auto-imports/globals.ts`20- Global type declarations: `storage/framework/auto-imports/globals.d.ts`21- Browser manifest: `storage/framework/browser-auto-imports.json`22- Server manifest: `storage/framework/server-auto-imports.json`23- Browser type declarations: `storage/framework/types/browser-auto-imports.d.ts` (~80KB)24- Server type declarations: `storage/framework/types/server-auto-imports.d.ts`25- General auto-import types: `storage/framework/types/auto-imports.d.ts`2627## How Auto-Imports Work2829### Browser Context (STX Templates)301. `storage/framework/browser-auto-imports.json` defines available imports (200+ entries)312. Types are declared in `storage/framework/types/browser-auto-imports.d.ts`323. STX plugin (`bun-plugin-stx`) resolves imports at build time334. Available in STX `<script>` tags without explicit `import` statements3435Browser auto-import injection applies to the STX script entry being compiled.36TypeScript modules imported by that script do not inherit its lexical bindings.37Every imported module must explicitly import the functions, stores, and types it38uses. A generated ambient declaration proves an identifier is available to an39STX entry; it does not make that identifier global inside bundled dependencies.4041### Server Context (Routes, Actions, Jobs)421. `storage/framework/server-auto-imports.json` defines server-side imports (100+ entries)432. Types are declared in `storage/framework/types/server-auto-imports.d.ts`443. All 60+ ORM models are auto-imported as globals454. Available in any server-side TypeScript file4647### Runtime Injection48`storage/framework/auto-imports/globals.ts` injects functions into `globalThis`:49```typescript50// Makes these available globally without imports:51globalThis.increment = increment52globalThis.count = count53globalThis.isDark = isDark54globalThis.toggleDark = toggleDark55// ... geo functions, GPX functions, etc.56```5758## What Gets Auto-Imported5960### Browser Auto-Imports (200+)61- **Composables**: useStorage, useLocalStorage, useFetch, useToggle, useCounter, useDark, useNow, etc.62- **Utilities**: debounce, throttle, retry, sleep, wait, delay, lazy, clamp, rand63- **Authentication**: useAuth, authGuard, auth64- **Formatting**: formatCurrency, formatDate, formatNumber, formatDuration65- **Browser Query Builder**: browserQuery, BrowserQueryBuilder, browserAuth, createBrowserModel66- **Payment**: confirmCardPayment, confirmPayment, createPaymentMethod, loadCardElement, loadPaymentElement67- **Stripe**: stripe instance68- **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)6970### Server Auto-Imports (100+)71- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (103 models)72- **Request Models**: UserRequest, PostRequest, OrderRequest, etc.73- **Actions**: Action types and helpers74- **Schema**: validation schema builder75- **Router**: route, response helpers76- **String Utilities**: slug, camelCase, pascalCase, snakeCase, kebabCase, titleCase77- **Core**: path, storage, log, handleError, Auth, register7879## Auto-Import Type Declarations8081### auto-imports.d.ts (general)82```typescript83declare global {84 const Action: typeof import('@stacksjs/actions').Action85 const response: typeof import('@stacksjs/router').response86 const route: typeof import('@stacksjs/router').route87 const schema: typeof import('@stacksjs/validation').schema88 const slug: typeof import('@stacksjs/strings').slug89 // ... all auto-imported identifiers90}91```9293### Adding Custom Auto-Imports94951. Create function in `resources/functions/`:96```typescript97// resources/functions/myUtils.ts98export function myHelper() { return 'hello' }99```1001012. Export from `storage/framework/auto-imports/functions.ts`:102```typescript103export { myHelper } from '../../resources/functions/myUtils'104```1051063. Declare types in `storage/framework/auto-imports/globals.d.ts`:107```typescript108declare function myHelper(): string109```1101114. Inject at runtime in `storage/framework/auto-imports/globals.ts`:112```typescript113globalThis.myHelper = myHelper114```115116## Generation Commands117118```bash119buddy generate # regenerate all auto-imports120buddy generate --types # regenerate type declarations121buddy generate --ide-helpers # regenerate IDE helpers122buddy generate:component-meta # regenerate component metadata123```124125The `build:reset` script also regenerates auto-imports.126127## Server Auto-Import Initialization128129```typescript130import { initiateImports, generateAutoImportFiles, injectGlobalAutoImports } from '@stacksjs/server'131132initiateImports() // initialize auto-import plugin133generateAutoImportFiles() // generate runtime auto-import files134injectGlobalAutoImports() // inject models/functions globally135```136137## Gotchas138- Browser auto-imports are resolved at BUILD TIME by bun-plugin-stx — not runtime139- Imported browser modules must declare their own imports; STX entry auto-imports do not leak into module scope140- Server auto-imports are injected into globalThis at RUNTIME141- The browser-auto-imports.d.ts file is ~80KB — it's auto-generated, don't edit manually142- Custom functions must be exported from both the function file AND the auto-imports barrel143- Type declarations must match the runtime globals for IDE support144- All 60+ ORM models are auto-imported on the server — available as `User.find(1)` etc.145- Request models (e.g., `UserRequest`) are also auto-imported for validated request access146- Auto-imports are regenerated during `buddy generate` and `build:reset`147- The discovered-packages.json file at `storage/framework/discovered-packages.json` is part of this system