Stacks Plugins
Key Paths
- Core package:
storage/framework/core/plugins/src/ - Source:
storage/framework/core/plugins/src/index.ts - Preloader:
storage/framework/defaults/resources/plugins/preloader.ts - Package:
@stacksjs/plugins
API
import { plugin } from '@stacksjs/plugins'
import type { BunPlugin, VitePlugin } from '@stacksjs/plugins'
The package exports:
plugin— Bun's native plugin factory for creating Bun pluginsBunPlugin— Type definition for Bun pluginsVitePlugin— Type definition for Vite plugins
Creating a Bun Plugin
import { plugin } from '@stacksjs/plugins'
import type { BunPlugin } from '@stacksjs/plugins'
const myPlugin: BunPlugin = {
name: 'my-plugin',
setup(build) {
build.onLoad({ filter: /\.custom$/ }, async (args) => {
const content = await Bun.file(args.path).text()
return { contents: transformContent(content), loader: 'ts' }
})
},
}
plugin(myPlugin)
Preloader
The framework preloader at storage/framework/defaults/resources/plugins/preloader.ts runs before the application starts:
- Configured in
bunfig.toml:preload = ["./storage/framework/defaults/resources/plugins/preloader.ts"] - Loads
bun-plugin-stxfor STX template processing - Initializes auto-imports and framework globals
Gotchas
- Thin wrapper — re-exports Bun's
pluginfactory and types for both Bun and Vite - Preloader is critical — the STX plugin (
bun-plugin-stx) must be preloaded for template processing to work - Two plugin systems — Bun plugins (runtime) and Vite plugins (build) are different APIs
- Plugins must be Bun-compatible — Node.js plugins won't work without adaptation
- Plugin preloader runs before app — any setup in preloader.ts happens before any application code
