Reference
Configuration reference
All configuration lives on one Blueprint, addressed by dotted stone.* keys. You rarely set most of them directly: decorators and blueprints write them for you. This is the map of what ends up there.
#Where keys come from
Three sources feed the Blueprint, resolved once at startup: your decorators (introspected into keys), imperative define* meta-modules, and the config passed to @StoneApp / defineStoneApp. Later sources refine earlier ones; the result is frozen before the first event.
#Core keys
| Key | Type | Purpose |
|---|---|---|
| stone.name | string | The application name. Defaults to "Stone.js". |
| stone.env | 'development' | 'production' | ... | The environment the app runs in. Defaults to production. |
| stone.debug | boolean | Detailed errors with stack traces. Off by default. |
| stone.locale / fallback_locale | string | Active and fallback locale. Both default to "en". |
| stone.timezone | string | Default timezone. Defaults to "UTC". |
| stone.logger | object | Logger settings, e.g. { level: "info" }. |
| stone.adapters | array | The stacked adapters. Usually set by adapter blueprints, not by hand. |
| stone.kernel.middleware | array | Global middleware every event flows through. |
| stone.kernel.errorHandlers | object | Maps error types to responses, kernel-wide. |
| stone.providers | array | Service providers loaded into the container. |
| stone.services / listeners / subscribers | array | Modules auto-registered at startup. |
| stone.aliases | object | Class aliases registered when the app starts. |
| stone.router | object | Router options (base path, strict matching); from @stone-js/router. |
Note the nesting: global middleware is stone.kernel.middleware, not stone.middleware. The kernel sub-tree holds everything the core applies per event; the top level holds what the app is.
#Build keys
The build namespace lives under stone.builder.* and is read by the CLI, not the kernel. It is the one place where a value shapes the artifact rather than the running app.
| Key | Type | Purpose |
|---|---|---|
| stone.builder.rendering | 'csr' | 'ssr' | 'ssg' | Pins the rendering strategy; deduced from the adapters when omitted. The --ssg flag selects ssg for one run. |
| stone.builder.input.mainCSS | string | Entry stylesheet, auto-linked. Defaults to /assets/css/index.css. |
| stone.builder.output | string | The build output directory. |
| stone.builder.ssg.routes | string[] | Extra static paths to pre-render, ADDED to the routes auto-derived from your pages. |
| stone.builder.dotenv | object | How .env files are loaded into the build. |
| stone.builder.excludedModules | string[] | Modules to keep out of the browser bundle. |
| stone.builder.vite / rollup | object | Escape hatches: raw Vite (frontend) or Rollup (backend) config. |
#Reading and setting
// read, with a default
const level = config.get('stone.logger.level', 'info')
// set, imperatively, in a meta-module
export const appConfig = { stone: { name: 'tasks', logger: { level: 'debug' } } }