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. (105 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