STX Templating Engine
STX is the full-stack templating and component framework for Stacks. It handles template rendering, reactivity, SSR, streaming, hydration, and more.
Design & anti-slop skills
When the task is how a page should look (not just how stx renders), pair this skill with the design-taste family: stacks-design-taste (flagship), the aesthetic presets stacks-design-soft / stacks-design-minimalist / stacks-design-brutalist, stacks-redesign, stacks-design-output, and the image-first stacks-image-to-code / stacks-imagegen-web / stacks-imagegen-mobile / stacks-brandkit. They translate premium design rules into stx + Crosswind + composables.
Key Paths
- STX config:
config/ui.ts - STX plugin:
bun-plugin-stx(loaded via bunfig.toml) - STX state:
.stx/ - Components:
resources/components/ - Layouts:
resources/layouts/ - Partials:
resources/partials/ - Views:
resources/views/ - Package:
@stacksjs/stx
CRITICAL Rules
- ALWAYS use STX for templating — never write vanilla JS
- NEVER use
var,document.*,window.*in STX templates - STX
<script>tags should ONLY contain stx-compatible code (signals, composables, directives)
Template Structure
<template>
<div class="container">
<h1>{{ title }}</h1>
<p x-if="showDescription">{{ description }}</p>
<button @click="increment">Count: {{ count }}</button>
</div>
</template>
<script>
import { ref, computed } from '@stacksjs/composables'
const count = ref(0)
const title = ref('Hello STX')
const showDescription = ref(true)
function increment() {
count.value++
}
</script>
<style>
/* Use crosswind utility classes or custom CSS */
.container { max-width: 1200px; margin: 0 auto; }
</style>
Configuration (config/ui.ts)
import type { StxOptions } from '@stacksjs/stx'
export default {
componentsDir: 'resources/components',
layoutsDir: 'resources/layouts',
partialsDir: 'resources/partials',
} satisfies StxOptions
Full StxConfig
interface StxConfig {
enabled: boolean
debug: boolean
componentsDir: string
partialsDir: string
layoutsDir?: string
defaultLayout?: string
templatesDir?: string
cachePath: string
ssr?: boolean
cache?: boolean
defaultTitle?: string
defaultDescription?: string
// Feature modules
i18n?: Partial<I18nConfig>
webComponents?: Partial<WebComponentConfig>
streaming?: Partial<StreamingConfig>
hydration?: Partial<HydrationConfig>
a11y?: Partial<A11yConfig>
seo?: Partial<SeoFeatureConfig>
animation?: Partial<AnimationConfig>
markdown?: Partial<MarkdownConfig>
forms?: Partial<FormConfig>
pwa?: Partial<PwaConfig>
components?: Partial<ComponentConfig>
media?: Partial<MediaConfig>
strict?: boolean | StrictModeConfig
customDirectives?: CustomDirective[]
}
STX Capabilities (118+ modules)
Core
- Template parsing and compilation
- Reactivity system (ref, computed, watch)
- Component composition and lifecycle
- Dependency injection (provide/inject)
Rendering
- SSR — Server-Side Rendering
- Streaming — Progressive HTML streaming
- Hydration — Progressive and islands-based hydration
- Suspense — Async component loading with fallbacks
- Error boundaries — Graceful error handling in components
Features
- Router — Client-side routing
- Forms — Built-in form handling and validation
- i18n — Internationalization support
- SEO — Meta tags, Open Graph, Twitter cards, structured data
- PWA — Progressive Web App support
- Animation — CSS and JS animation system
- Markdown — Markdown rendering with syntax highlighting
- A11y — Accessibility checking and auto-fixing
Dev Tools
- Dev server with HMR (Hot Module Replacement)
- Image optimization
- Asset pipeline
- Testing utilities
Plugin Loading
# bunfig.toml
[serve]
plugins = ["bun-plugin-stx"]
The STX plugin processes .stx files during serve and build.
Scaffolding
import { createProject, addComponent, addPage, addStore, addLayout } from '@stacksjs/stx'
// Create a new project
await createProject('my-app', { template: 'dashboard' })
// Add to existing project
await addComponent('UserCard', { props: true, styles: true })
await addPage('about', { layout: 'default' })
await addStore('cart', { persist: true, actions: true })
await addLayout('admin', { nav: true, footer: true })
Project Templates
default, minimal, full, blog, dashboard, landing
Gotchas
- STX is the ONLY templating system — do not use other template engines
bun-plugin-stxmust be loaded — without it,.stxfiles won't be processed- Auto-imports — browser auto-imports defined in
storage/framework/browser-auto-imports.json .stx/directory — contains STX-specific state and cache- Reactivity is custom —
ref()andcomputed()from STX are not Vue's implementation - Crosswind for styling — use utility classes, not inline styles
- Script block restrictions — only stx-compatible code (signals, composables, directives), no vanilla DOM APIs
- Components go in
resources/— not inapp/orstorage/ - 118+ modules — STX is a comprehensive framework covering rendering, routing, forms, i18n, SEO, PWA, and more
