# Stacks Auto Imports

> 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/.

- Skill: `stacksjs/stacks-auto-imports` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stacksjs/stacks-auto-imports`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stacksjs/stacks-auto-imports/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: stacksjs (https://skillmd.com/u/stacksjs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stacksjs/stacks-auto-imports

---


# 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

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)
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`:
```typescript
// 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. (97 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)
```typescript
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/`:
```typescript
// resources/functions/myUtils.ts
export function myHelper() { return 'hello' }
```

2. Export from `storage/framework/auto-imports/functions.ts`:
```typescript
export { myHelper } from '../../resources/functions/myUtils'
```

3. Declare types in `storage/framework/auto-imports/globals.d.ts`:
```typescript
declare function myHelper(): string
```

4. Inject at runtime in `storage/framework/auto-imports/globals.ts`:
```typescript
globalThis.myHelper = myHelper
```

## Generation Commands

```bash
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

```typescript
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