Stacks Configuration

Read the application's config/*.ts and exported types before proposing a
setting. Config is typed executable code; a copied options inventory can drift.

Loading and readiness

import { config, overridesReady } from '@stacksjs/config'

await overridesReady
const applicationName = config.app.name

The config proxy merges framework defaults with asynchronous application
overrides. Read it after overridesReady when initializing a driver or caching a
scalar setting. Destructuring before readiness can capture a default forever.
The readiness promise and override storage are shared across installed copies.
Compiled server builds have a separate minimal env config and may deliberately
set SKIP_CONFIG_LOADING=true; see stacks-server.

Individual exports (app, auth, database, queue, filesystems and others) are also
available. Use the matching satisfies ...Config type or define helper.
defineModel belongs to @stacksjs/orm. App registries are owned by their
packages: defineEvents/defineListener by events, defineMiddleware by router,
defineGates by auth and defineCommand by cli.

Driver capability evidence

capabilityRegistry, capabilityDrivers(category),
findCapability(category, name) and assertCapabilityAvailable are
exported by @stacksjs/config. Read status, topology, prerequisites,
limitations and testEvidence before promising provider support.

• Supported local drivers have retained local tests. Supported remote drivers
  name a version and CI workflow in liveServiceContract.
• Partial drivers have an implementation with narrower retained evidence.
  For S3/Azure and external mail this includes request/signature/config checks,
  without a live object round-trip or delivery assertion.
• Experimental drivers are usable within their documented limitations, without
  the supported conformance claim.
• Unsupported and unknown drivers throw through assertCapabilityAvailable.
  A config-shaped entry alone is not an implemented runtime driver.

validateConfig(snapshot) returns path/message issues; reportConfigIssues
prints them. Boot validation checks important known fields, not every possible
option. Read validators.ts before treating it as a complete schema validator.

Framework feature gates

feature(name) reads a bundle's config/<name>.ts. Explicit runtime
enableFeature/disableFeature overrides win, then config enabled and its optional
env allowlist, then framework fallback (dashboard is on when config is absent).
resetFeature removes a runtime override; listFeatures snapshots the known set.

Use buddy features and the bundle's install/uninstall commands to inspect
and change installed feature resources. Runtime config gates and installation
are related but not interchangeable. The auth gate controls account-family
model loading; default auth routes are selected by STACKS_DEFAULT_ROUTES.
The email gate controls the implicit email webhook route bundle.

Application config flags augment AppFeatureFlags. Runtime targeting,
experiments and persisted user flags belong to the separate native
@stacksjs/feature-flags package. Read its exports/config before using it;
feature() is not an A/B allocation API.

Native resource discovery

Discovered packages can contribute routes, models, jobs, migrations, views and
explicitly opted-in components through their package Stacks metadata.
packageModelRoots/packageJobRoots/packageMigrationRoots/packageViewRoots/ packageComponentRootsreadstorage/framework/discovered-packages.json.
Missing manifests mean no package resources. Component directories are opt-in
because bare tag names enter a global template namespace. Package migration
sources are copied before any preprocessing; installed package files are read
as resources, not rewritten in place. See stacks-plugins.

Default view selection uses resolveViewPatterns and the exported bundle
metadata. Request-local configuration context lives in request-context.ts:
useRequestEvent() reads the scoped request snapshot, while entrypoints
install scopes. Request context must be established per request; globals or
cached snapshots cannot represent concurrent users.

Configuration paths

Concern	Read
application, SEO, launch	app.ts
model connection and SQL behavior	database.ts, query-builder.ts
credentials, sessions, cookies, OAuth, magic links	auth.ts, hashing.ts
model API exposure and row ownership	security.ts
background work and cache	queue.ts, cache.ts
uploads and disks	filesystems.ts, default local disk
mail, SMS and notifications	email.ts, sms.ts, notification.ts, services.ts
deployment	cloud.ts, its named tsCloud export and default wrapper
frontend	stx.ts, css.ts, ui.ts
agent installation	app/Skills/, defaults/ai/, stacks-skills package

Use stacks-env for validated/coerced environment variables, encrypted files
and shared-box tenant isolation. Config files hold expressions referencing env;
editing a nested live object is not the same as persisting that source file.

Sources and verification

Public contract: storage/framework/core/config/src/index.ts,
config.ts, overrides.ts, capabilities.ts,
features.ts, discovered-resources.ts and request-context.ts.
Retained tests are under core/config/tests/; driver readiness also has
core/search-engine/tests/early-proxy.test.ts.