Configuration

STX is configured through stx.config.ts (or .config/stx.config.ts) in your project root.

Stacks projects may also keep shared UI configuration in config/ui.ts. When both files exist, stx shallow-merges them: keys from config/ui.ts are retained and keys declared in the root file win. This lets a root config override root, debug, or another setting without silently dropping UI plugins.

// config/ui.ts
export default {
  plugins: ['@stacksjs/components/stx-plugin'],
}

// stx.config.ts
export default {
  root: 'resources',
}

Basic Configuration

// stx.config.ts
import type { StxConfig } from '@stacksjs/stx'

export default {
  // Component directories
  componentsDir: './components',
  partialsDir: './partials',

  // Caching
  cache: true,
  cachePath: '.stx/cache',

  // Development
  debug: false,

  // Custom directives
  customDirectives: [],

  // Middleware
  middleware: [],
} satisfies StxConfig

Configuration Options

Directories

export default {
  // Where to find components
  componentsDir: './components',

  // Where to find partial templates
  partialsDir: './partials',

  // Output directory for builds
  outDir: './dist',
}

State directory

Everything stx generates for a project that is neither source nor a build artifact you ship lives under one directory: the compiled-template cache, the Css CSS cache, the client-script bundle cache and its temp directory, the generated route manifest and route types, dev-server output, SSG and media caches, and story snapshots. It defaults to a hidden .stx/ in the project root.

Point it elsewhere if your project already has a home for generated state:

export default {
  // A Stacks application keeps every runtime-owned directory under storage/.
  stateDir: 'storage/framework/stx',
}

The path-shaped options that default to somewhere under .stx/ follow this setting - cachePath, build.cacheDir, media.cache.directory and story.outDir. A path you point somewhere else entirely is left alone.

Relative paths resolve against the project root; absolute paths are used as-is. STX_DIR overrides the config, which is how a framework driving stx keeps itself and the processes it spawns in agreement.

Caching

Template caching improves performance in production:

export default {
  // Enable/disable caching
  cache: process.env.NODE_ENV === 'production',

  // Cache directory
  cachePath: '.stx/cache',

  // Cache TTL in milliseconds (optional)
  cacheTTL: 3600000,  // 1 hour
}

Debug Mode

Enable detailed error logging:

export default {
  // Enable debug mode
  debug: process.env.NODE_ENV !== 'production',

  // Verbose logging
  verbose: false,
}

Custom Directives

Register custom directives:

import type { CustomDirective } from '@stacksjs/stx'

const uppercase: CustomDirective = {
  name: 'uppercase',
  handler: (content, params) => params[0]?.toUpperCase() || content.toUpperCase(),
  hasEndTag: false,
  description: 'Converts text to uppercase',
}

export default {
  customDirectives: [uppercase],
}

Middleware

Add pre/post-processing middleware:

export default {
  middleware: [
    {
      name: 'minify',
      timing: 'after',  // 'before' or 'after'
      handler: (html) => html.replace(/\s+/g, ' '),
    },
  ],
}

Internationalization

Configure i18n support:

export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr', 'de'],
    translations: {
      en: { greeting: 'Hello' },
      es: { greeting: 'Hola' },
      fr: { greeting: 'Bonjour' },
      de: { greeting: 'Hallo' },
    },
  },
}

Web Components

Generate web components from templates:

export default {
  webComponents: {
    enabled: true,
    prefix: 'x',
    shadowDOM: true,
    components: ['Card', 'Button', 'Modal'],
  },
}

Plugin Configuration

Configure the Bun plugin:

// build.ts
import { stxPlugin } from 'bun-plugin-stx'

await Bun.build({
  entrypoints: ['./src/index.stx'],
  plugins: [
    stxPlugin({
      // Override config options
      debug: true,
      componentsDir: './src/components',
    }),
  ],
})

Environment Variables

STX respects these environment variables:

Complete Example

// stx.config.ts
import type { StxConfig, CustomDirective } from '@stacksjs/stx'

// Custom directive
const currency: CustomDirective = {
  name: 'currency',
  handler: (content, [amount, currency = 'USD']) => {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency,
    }).format(Number(amount))
  },
}

export default {
  // Directories
  componentsDir: './components',
  partialsDir: './partials',
  outDir: './dist',

  // Caching
  cache: process.env.NODE_ENV === 'production',
  cachePath: '.stx/cache',

  // Development
  debug: process.env.NODE_ENV !== 'production',
  verbose: false,

  // Custom directives
  customDirectives: [currency],

  // Middleware
  middleware: [
    {
      name: 'timing',
      timing: 'after',
      handler: (html) => {
        return `<!-- Generated: ${new Date().toISOString()} -->\n${html}`
      },
    },
  ],

  // i18n
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es'],
    translations: {
      en: {
        welcome: 'Welcome',
        goodbye: 'Goodbye',
      },
      es: {
        welcome: 'Bienvenido',
        goodbye: 'Adios',
      },
    },
  },

  // Web Components
  webComponents: {
    enabled: true,
    prefix: 'stx',
    shadowDOM: true,
  },
} satisfies StxConfig

Related

• Getting Started
• Custom Directives
• Server-Side Rendering