Configuration

This is just an example of the ts-starter docs.

The Reverse Proxy can be configured using a reverse-proxy.config.ts (or reverse-proxy.config.js) file and it will be automatically loaded when running the reverse-proxy command.

// reverse-proxy.config.{ts,js}
import type { ReverseProxyOptions } from '@stacksjs/rpx'
import os from 'node:os'
import path from 'node:path'

const config: ReverseProxyOptions = {
  /**
   * The from URL to proxy from.
   * Default: localhost:5173
   */
  from: 'localhost:5173',

  /**
   * The to URL to proxy to.
   * Default: stacks.localhost
   */
  to: 'stacks.localhost',

  /**
   * The HTTPS settings.
   * Default: true
   * If set to false, the proxy will use HTTP.
   * If set to true, the proxy will use HTTPS.
   * If set to an object, the proxy will use HTTPS with the provided settings.
   */
  https: {
    domain: 'stacks.localhost',
    hostCertCN: 'stacks.localhost',
    caCertPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.ca.crt`),
    certPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt`),
    keyPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt.key`),
    altNameIPs: ['127.0.0.1'],
    altNameURIs: ['localhost'],
    organizationName: 'stacksjs.org',
    countryName: 'US',
    stateName: 'California',
    localityName: 'Playa Vista',
    commonName: 'stacks.localhost',
    validityDays: 180,
    verbose: false,
  },

  /**
   * The verbose setting.
   * Default: false
   * If set to true, the proxy will log more information.
   */
  verbose: false,
}

export default config

Then run:

./rpx start

To learn more, head over to the documentation.

stx can be configured using a stx.config.ts file in your project root. This guide covers all available configuration options and their usage.

Basic Configuration

A minimal configuration file looks like this:

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

export default defineConfig({
  // Project name
  name: 'my-stx-app',

  // Project root directory
  root: '.',

  // Build output directory
  outDir: 'dist',

  // Development server options
  server: {
    port: 3000,
    host: 'localhost'
  }
})

Full Configuration Reference

Here's a complete configuration file with all available options:

import { defineConfig } from '@stacksjs/stx'

export default defineConfig({
  // Project name
  name: 'my-stx-app',

  // Project root directory
  root: '.',

  // Build output directory
  outDir: 'dist',

  // Source directory
  srcDir: 'src',

  // Public assets directory
  publicDir: 'public',

  // Base public path
  base: '/',

  // Development server configuration
  server: {
    port: 3000,
    host: 'localhost',
    https: false,
    open: true, // Open browser on server start
    cors: true, // Enable CORS
    hmr: true,  // Hot Module Replacement
  },

  // Build configuration
  build: {
    target: 'esnext',
    minify: true,
    sourcemap: true,
    // Custom build options
    rollupOptions: {
      // Rollup-specific options
    }
  },

  // Feature flags
  features: {
    typescript: true,   // Enable TypeScript support
    streaming: true,    // Enable streaming rendering
    components: true,   // Enable component system
    devtools: true,     // Enable DevTools in development
  },

  // Template configuration
  template: {
    // Default template engine options
    engine: 'stx',
    // Template file extension
    extension: '.stx',
    // Global template data
    data: {
      site: {
        title: 'My stx App',
        description: 'Built with stx'
      }
    }
  },

  // Plugin system
  plugins: [
    // Add your plugins here
  ],

  // Optimization options
  optimize: {
    minify: true,
    treeshake: true,
    splitting: true
  },

  // Development tools
  devtools: {
    enabled: true,
    port: 9090
  },

  // TypeScript configuration
  typescript: {
    // TypeScript compiler options
    compilerOptions: {
      strict: true,
      target: 'esnext',
      module: 'esnext'
    }
  }
})

Configuration Options

Project Options

Server Options

Build Options

Feature Flags

Static Files

Anything you place under publicDir (default: public/) is served at the URL root by the dev server. This matches the Nuxt/Vite/Next/Astro convention:

my-app/
├── pages/
│   └── index.stx          → /
├── public/
│   ├── favicon.ico        → /favicon.ico
│   ├── robots.txt         → /robots.txt
│   ├── images/
│   │   └── hero.jpg       → /images/hero.jpg
│   └── fonts/
│       └── inter.woff2    → /fonts/inter.woff2
└── stx.config.ts

In your templates, reference them with absolute paths:

<img src="/images/hero.jpg" alt="Hero">
<link rel="icon" href="/favicon.ico">

Notes:

• Files are served with appropriate Content-Type headers — .jpg → image/jpeg, .svg → image/svg+xml, .woff2 → font/woff2, etc. Common types covered: images (png, jpg, gif, webp, avif, svg, ico, bmp), fonts (woff, woff2, ttf, otf, eot), media (mp4, webm, mp3, wav, ogg), text (txt, xml, html, json), and pdf.
• Pages take precedence — if you have both pages/about.stx and public/about.html, the page wins. Public files are only served when no page route matches.
• Path traversal is blocked: requests like /../package.json or /images/../../secret.json are rejected, never read.
• The favicon at public/favicon.ico is served automatically. If no favicon exists, /favicon.ico returns a 204 to stop the browser nagging.

To override the directory name, set publicDir in stx.config.ts:

export default defineConfig({
  publicDir: 'static',  // serve from static/ instead of public/
})

Or override per-server when calling serve() programmatically:

import { serve } from 'bun-plugin-stx/serve'

await serve({
  patterns: ['pages/'],
  publicDir: 'public',  // explicit override
  port: 3000,
})

Environment Variables

stx also supports environment variables for configuration. Create a .env file in your project root:

# .env
stx_PORT=3000
stx_HOST=localhost
stx_PUBLIC_DIR=public

Environment variables take precedence over configuration file values.

TypeScript Configuration

stx works best with TypeScript. Here's a recommended tsconfig.json:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "preserve",
    "skipLibCheck": true,
    "isolatedModules": true,
    "types": ["@stacksjs/stx/types"]
  },
  "include": ["src/**/*.ts", "src/**/*.stx"],
  "exclude": ["node_modules", "dist"]
}

Plugin System

stx supports plugins for extending functionality:

import { defineConfig } from '@stacksjs/stx'
import markdown from '@stacksjs/stx-markdown'

// Note: CSS is generated separately using Headwind
// Run: bun run build:css to generate utility CSS
// See headwind.config.ts for CSS configuration

export default defineConfig({
  plugins: [
    markdown({
      // Plugin options
    })
  ]
})

Next Steps

• Learn about Template Syntax
• Explore Component Configuration
• Check out Plugin Development