stacks-alias - SKILL.md Agent Skill

name: stacks-alias description: Use when working with path aliases in a Stacks project — import resolution, module aliasing, or debugging import paths. Covers @stacksjs/alias which defines 260+ path mappings for the entire framework. license: MIT compatibility: Bun >= 1.3.0, TypeScript allowed-tools: Read Edit Write Bash Grep Glob

Stacks Path Aliases

Key Paths

Core package: storage/framework/core/alias/src/
Source: storage/framework/core/alias/src/index.ts
Package: @stacksjs/alias

API

import { alias } from '@stacksjs/alias'

const alias: Record<string, string>  // 260+ entries

Alias Categories

Framework Module Aliases

Maps @stacksjs/* and stacks/* imports to their source files:

'@stacksjs/ai':          'storage/framework/core/ai/src/index.ts'
'@stacksjs/auth':        'storage/framework/core/auth/src/index.ts'
'@stacksjs/database':    'storage/framework/core/database/src/index.ts'
'@stacksjs/router':      'storage/framework/core/router/src/index.ts'
'@stacksjs/cache':       'storage/framework/core/cache/src/index.ts'
'@stacksjs/cli':         'storage/framework/core/buddy/src/index.ts'
'@stacksjs/config':      'storage/framework/core/config/src/index.ts'
// ... all core packages

Both @stacksjs/ and stacks/ prefixes are supported:

'stacks/auth':            'storage/framework/core/auth/src/index.ts'
'stacks/database':        'storage/framework/core/database/src/index.ts'

Config Aliases

Maps ~/config/* to config files:

'~/config/database':      'config/database.ts'
'~/config/dns':           'config/dns.ts'
'~/config/docs':          'config/docs.ts'
'~/config/email':         'config/email.ts'
// ... all 44 config files

Resource Aliases

Maps ~/ paths to project directories:

'~/app/*':                'app/*'
'~/components/*':         'resources/components/*'
'~/functions/*':          'resources/functions/*'
'~/views/*':              'resources/views/*'
'~/lang/*':               'locales/*'
'~/*':                    '*'

Framework Aliases

'framework/*':            'storage/framework/*'
'@/*':                    '*'

Usage

Aliases are automatically resolved by Bun at runtime and by the build system for production:

// These all work because of aliases
import { db } from '@stacksjs/database'
import { route } from '@stacksjs/router'
import { auth } from 'stacks/auth'
import dbConfig from '~/config/database'

Gotchas

260+ entries — covers every core package, config file, and resource directory
Dual prefixes — both @stacksjs/ and stacks/ resolve to the same source files
Runtime resolution — Bun resolves these at runtime via bunfig.toml preloading
Build-time resolution — the build system resolves aliases to actual paths for production
Always use aliases — never use relative paths between packages in the monorepo
Adding new packages — requires adding alias entries for both @stacksjs/ and stacks/ prefixes