Configuration
Configuration
Configure x via x.config.ts at your project root. Use defineConfig from @thexjs/core for type-safe configuration.
defineConfig
All configuration options are optional. x provides sensible defaults so you can start with zero configuration and add settings as needed.
import { defineConfig } from "@thexjs/core";export default defineConfig({ // Page routes pagesDir: "src/pages", // Layout directory (for root layouts) layoutsDir: "src/layouts", // API routes apiDir: "src/api", // Server functions actionsDir: "src/actions", // Content collections (markdown) contentDir: "content", // Dev server port port: 3000, // Security guardrails (headers, CSRF, rate limiting) security: { csrf: { requireToken: true }, headers: { contentSecurityPolicy: "default-src 'self'; script-src 'self'" }, rateLimit: { limit: 120 }, }, // Observability (logging, health probes, error reporting) observability: { logging: true, health: { check: () => ({ status: "ok" }) }, errorReporter: (err, ctx) => console.error(err, ctx), }, // Remote image proxy allow-list images: { remoteHosts: ["cdn.example.com"], }, // Legacy routes directory routesDir: "src/routes",});All options reference
Option Type Default Description─────────────────────────────────────────────────────────────pagesDir string "src/pages" File-based page routeslayoutsDir string "src/layouts" Root layout directoryapiDir string "src/api" File-based API routesactionsDir string "src/actions" Server functionscontentDir string undefined Markdown content collectionsport number 3000 Dev server portroutesDir string undefined Legacy routes directorydevelopment boolean false Force dev-mode behaviorstylesheetHref string undefined Precomputed stylesheet <link> hrefsecurity.csrf object|false enabled CSRF for /__x/actions/*security.headers object|false enabled CSP, HSTS, X-Frame-Options, ...security.rateLimit object|false enabled Per-IP fixed-window limiterobservability.logging boolean true Structured JSON request logsobservability.errorReporter fn undefined Plugin for exceptions (Sentry/OTel)observability.health object undefined /healthz + /readyz endpointsimages.remoteHosts string[] undefined /_x/image proxy allow-listpagesDir
The directory containing your page route files. Defaults to src/pages. Each .tsx file becomes a route based on its file path.
layoutsDir
The directory for root layout components. Layouts wrap pages and can be nested using the _layout.tsx convention inside page directories.
apiDir
The directory for API route files. Files here respond to HTTP methods (GET, POST, etc.) and are served under /api/....
actionsDir
The directory for server functions. Exported async functions can be called from the browser via fetch('/__x/actions/...'). If you don't set this, x auto-detects a src/actions directory.
contentDir
The directory for markdown content collections. Files with frontmatter are scanned, and each becomes a route at its own path. Load content via scanContent and renderMarkdown.
port
The port number for the dev server. Defaults to 3000.
security
Nested options for the security guardrails: csrf (origin verification + optional double-submit token), headers (CSP, HSTS, frame options, nosniff), and rateLimit (per-IP fixed-window limiter, optionally backed by a Redis store). Pass false for any of them to disable it. See Security for the full reference.
observability
logging toggles structured JSON request logs, health enables the /healthz and /readyz probes, and errorReporter plugs exceptions into Sentry, OTel, or your own handler. See Observability.
images
remoteHosts allow-lists hosts for the /_x/image?url=... proxy, so a strict img-src 'self' CSP can still load remote images through your own origin.
routesDir (legacy)
A legacy option for projects migrating from earlier versions of X. Maps to the same file-based routing convention. Prefer pagesDir for new projects.