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 build cache + route manifest:
storage/framework/stx/ (stx's stateDir, set in config/ui.ts)
- 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-stx must be loaded — without it, .stx files won't be processed
- Auto-imports — browser auto-imports defined in
storage/framework/browser-auto-imports.json
storage/framework/stx/ — stx build cache and the generated route manifest. config/ui.ts sets stx's stateDir here, so nothing lands in the project root. Gitignored; safe to delete
- Reactivity is custom —
ref() and computed() 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 in app/ or storage/
- 118+ modules — STX is a comprehensive framework covering rendering, routing, forms, i18n, SEO, PWA, and more
1---2name: stacks-stx-33description: Use when working with STX templates in a Stacks application — template syntax, components, directives, signals, reactivity, SSR, streaming, hydration, or debugging STX rendering. STX is the ONLY templating system for Stacks.4license: MIT5---67# STX Templating Engine89STX is the full-stack templating and component framework for Stacks. It handles template rendering, reactivity, SSR, streaming, hydration, and more.1011## Design & anti-slop skills1213When 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.1415## Key Paths16- STX config: `config/ui.ts`17- STX plugin: `bun-plugin-stx` (loaded via bunfig.toml)18- STX build cache + route manifest: `storage/framework/stx/` (stx's `stateDir`, set in `config/ui.ts`)19- Components: `resources/components/`20- Layouts: `resources/layouts/`21- Partials: `resources/partials/`22- Views: `resources/views/`23- Package: `@stacksjs/stx`2425## CRITICAL Rules261. **ALWAYS use STX** for templating — never write vanilla JS272. **NEVER use** `var`, `document.*`, `window.*` in STX templates283. STX `<script>` tags should ONLY contain stx-compatible code (signals, composables, directives)2930## Template Structure3132```html33<template>34 <div class="container">35 <h1>{{ title }}</h1>36 <p x-if="showDescription">{{ description }}</p>37 <button @click="increment">Count: {{ count }}</button>38 </div>39</template>4041<script>42import { ref, computed } from '@stacksjs/composables'4344const count = ref(0)45const title = ref('Hello STX')46const showDescription = ref(true)4748function increment() {49 count.value++50}51</script>5253<style>54/* Use crosswind utility classes or custom CSS */55.container { max-width: 1200px; margin: 0 auto; }56</style>57```5859## Configuration (config/ui.ts)6061```typescript62import type { StxOptions } from '@stacksjs/stx'6364export default {65 componentsDir: 'resources/components',66 layoutsDir: 'resources/layouts',67 partialsDir: 'resources/partials',68} satisfies StxOptions69```7071### Full StxConfig7273```typescript74interface StxConfig {75 enabled: boolean76 debug: boolean77 componentsDir: string78 partialsDir: string79 layoutsDir?: string80 defaultLayout?: string81 templatesDir?: string82 cachePath: string83 ssr?: boolean84 cache?: boolean85 defaultTitle?: string86 defaultDescription?: string8788 // Feature modules89 i18n?: Partial<I18nConfig>90 webComponents?: Partial<WebComponentConfig>91 streaming?: Partial<StreamingConfig>92 hydration?: Partial<HydrationConfig>93 a11y?: Partial<A11yConfig>94 seo?: Partial<SeoFeatureConfig>95 animation?: Partial<AnimationConfig>96 markdown?: Partial<MarkdownConfig>97 forms?: Partial<FormConfig>98 pwa?: Partial<PwaConfig>99 components?: Partial<ComponentConfig>100 media?: Partial<MediaConfig>101 strict?: boolean | StrictModeConfig102 customDirectives?: CustomDirective[]103}104```105106## STX Capabilities (118+ modules)107108### Core109- Template parsing and compilation110- Reactivity system (ref, computed, watch)111- Component composition and lifecycle112- Dependency injection (provide/inject)113114### Rendering115- **SSR** — Server-Side Rendering116- **Streaming** — Progressive HTML streaming117- **Hydration** — Progressive and islands-based hydration118- **Suspense** — Async component loading with fallbacks119- **Error boundaries** — Graceful error handling in components120121### Features122- **Router** — Client-side routing123- **Forms** — Built-in form handling and validation124- **i18n** — Internationalization support125- **SEO** — Meta tags, Open Graph, Twitter cards, structured data126- **PWA** — Progressive Web App support127- **Animation** — CSS and JS animation system128- **Markdown** — Markdown rendering with syntax highlighting129- **A11y** — Accessibility checking and auto-fixing130131### Dev Tools132- **Dev server** with HMR (Hot Module Replacement)133- **Image optimization**134- **Asset pipeline**135- **Testing utilities**136137## Plugin Loading138139```toml140# bunfig.toml141[serve]142plugins = ["bun-plugin-stx"]143```144145The STX plugin processes `.stx` files during serve and build.146147## Scaffolding148149```typescript150import { createProject, addComponent, addPage, addStore, addLayout } from '@stacksjs/stx'151152// Create a new project153await createProject('my-app', { template: 'dashboard' })154155// Add to existing project156await addComponent('UserCard', { props: true, styles: true })157await addPage('about', { layout: 'default' })158await addStore('cart', { persist: true, actions: true })159await addLayout('admin', { nav: true, footer: true })160```161162### Project Templates163`default`, `minimal`, `full`, `blog`, `dashboard`, `landing`164165## Gotchas166- **STX is the ONLY templating system** — do not use other template engines167- **`bun-plugin-stx` must be loaded** — without it, `.stx` files won't be processed168- **Auto-imports** — browser auto-imports defined in `storage/framework/browser-auto-imports.json`169- **`storage/framework/stx/`** — stx build cache and the generated route manifest. `config/ui.ts` sets stx's `stateDir` here, so nothing lands in the project root. Gitignored; safe to delete170- **Reactivity is custom** — `ref()` and `computed()` from STX are not Vue's implementation171- **Crosswind for styling** — use utility classes, not inline styles172- **Script block restrictions** — only stx-compatible code (signals, composables, directives), no vanilla DOM APIs173- **Components go in `resources/`** — not in `app/` or `storage/`174- **118+ modules** — STX is a comprehensive framework covering rendering, routing, forms, i18n, SEO, PWA, and more