API / API reference 10 min read
Configuration reference Top-level ZeruxConfig options, defaults, precedence and lifecycle effects.
↗ View Markdown Save page Copy Markdown In plain language A type table is a contract, not a list of automatically enabled features. Find the setup guide for the service before copying an option into config.
Look up a word · Learn step by step zerux.config.ts exports a configuration object, usually a default export typed with ZeruxConfig. Configuration is application startup input, not browser configuration.
Project and discovery# Option Shape / default Behavior typefix, dynamic, function; default fixStructure mode entryPointstring; default index Optional application registration module basename outDirstring; default .zerux Runtime output directory; build safety checks constrain output structure.appstring; default app File-route root structure.middlewarestring or array; default middleware Global middleware discovery structure.controllersstring or array; default controllers Controller discovery structure.composablesstring or array; default composables Composable discovery structure.pluginsstring or array; default plugins Plugin discovery structure.publicstring or array; default public Public assets structure.envstring or array Additional environment files
Server and host options# server.port, server.devPort, server.allowedDomains and server.allowedDevDomain configure the server. Runtime host checks prefer nested server.allowedDomains / server.allowedDevDomain over top-level aliases. An allowed hostname is not an authentication policy. Keep confidential assets out of public directories.
Database and cache# db (with backward-compatible database) selects named connections. connectorManager defaults to the shared database manager package. cache takes connector, options, prefix, defaultTtlSeconds, startupTimeoutMs and required. Do not confuse runtime cache.connector with standalone createCacheManager({helper}) configuration.
Managed services# Key Main role Dependencies / policy filesNamed local/S3 stores Storage credentials and application access policy emailSMTP, optional inbound mail, tracking/preferences Named accounts; DB/files/analytics where configured analyticsNamed DB event pipeline Best-effort event persistence tagsBrowser/server tag manager Analytics, destinations and explicit admin authorization reportsAuthenticated report studio Analytics source/store and host authorization queueRedis/BullMQ producers/workers Explicit Redis config, queues and optional processors
Initialization strips private service settings before exposing runtime config. Service credentials still belong in protected server environment/secret storage. Configuration alone does not supply session authentication for dashboards.
Workers, protocols and rendering# worker.minThreads and worker.maxThreads set thread-worker defaults. protocols configures gateway authorization/origins and endpoint behavior. multisite: true enables request registration of host/path mappings. theme supplies the built-in theme configuration. websocket controls the existing websocket integration. devtools.modules lists optional modules as strings or {package,enabled,options} objects.
Extensibility and validation# The interface permits additional keys for extensions; accepting a key at type level does not mean a built-in implementation consumes it. Read the linked source and service types for nested options. Validate environment values at startup, and do not use configuration output as a debugging response on a public route.
JavaScript configuration# See zerux.config.js for an ESM JavaScript example, file precedence, environment timing and the documentation app configuration.
Configuration handbook# Choose the section matching the service you are enabling. Every page separates runtime setup from standalone factories and includes JavaScript, TypeScript, prerequisites, failure behavior and verification.
Complete root option contracts# These are the declared shapes of the current source version. A type declaration is not evidence of automatic runtime consumption: auth, security, websocket and custom keys require checking their actual integration path. The root config has an open index signature for application extensions; unknown keys are not automatically initialized.
ZeruxConfig# Option Accepted TypeScript value Required Meaning filesimport('./bootstrap/services.js').FilesStartupConfigNo Named storage connections; initialized before email service. emailimport('./bootstrap/services.js').EmailStartupConfigNo Named SMTP providers. Never serialized into runtime manifests. analyticsimport('./bootstrap/services.js').AnalyticsStartupConfigNo Best-effort telemetry backed by a named database connector. tagsimport('./bootstrap/services.js').TagsStartupConfigNo GA4-style event tags and browser ttag script, managed as a private service. reportsimport('./bootstrap/services.js').ReportsStartupConfigNo Authenticated internal analytics report studio. queueimport('./bootstrap/services.js').QueueStartupConfigNo BullMQ queues and optional workers. Credentials remain server-side. protocolsimport("./protocols.js").ZeruxProtocolOptionsNo Passed using this declared shape; omission is allowed only when marked optional. type"fix" | "dynamic" | "function"No Passed using this declared shape; omission is allowed only when marked optional. entryPointstringNo Passed using this declared shape; omission is allowed only when marked optional. outDirstringNo Passed using this declared shape; omission is allowed only when marked optional. multisitebooleanNo Passed using this declared shape; omission is allowed only when marked optional. structureZeruxStructureConfigNo Passed using this declared shape; omission is allowed only when marked optional. serverZeruxServerConfigNo Passed using this declared shape; omission is allowed only when marked optional. devtoolsZeruxDevtoolsConfigNo Passed using this declared shape; omission is allowed only when marked optional. workerZeruxWorkerConfigNo Passed using this declared shape; omission is allowed only when marked optional. allowedDomainsstring | string[]No Passed using this declared shape; omission is allowed only when marked optional. allowedDevDomainstringNo Passed using this declared shape; omission is allowed only when marked optional. connectorManagerstringNo Passed using this declared shape; omission is allowed only when marked optional. dbDatabaseConfigNo Passed using this declared shape; omission is allowed only when marked optional. databaseDatabaseConfigNo Passed using this declared shape; omission is allowed only when marked optional. websocket{ enabled?: boolean; path?: string; maxPayload?: number; }No Passed using this declared shape; omission is allowed only when marked optional. cache{ connector?: string; options?: Record<string, unknown>; prefix?: string; defaultTtlSeconds?: number; startupTimeoutMs?: number; required?: boolean; }No Passed using this declared shape; omission is allowed only when marked optional. securitySecurityConfigNo Passed using this declared shape; omission is allowed only when marked optional. authAuthConfigNo Passed using this declared shape; omission is allowed only when marked optional. themeimport("./theme.js").ThemeConfigNo Passed using this declared shape; omission is allowed only when marked optional.
DatabaseConfig# Option Accepted TypeScript value Required Meaning defaultstringNo Passed using this declared shape; omission is allowed only when marked optional. connectionsDatabaseConnection[]No Passed using this declared shape; omission is allowed only when marked optional. connectionDatabaseConnection[]No Passed using this declared shape; omission is allowed only when marked optional.
DatabaseConnection# Option Accepted TypeScript value Required Meaning namestringYes Passed using this declared shape; omission is allowed only when marked optional. slugstringYes Passed using this declared shape; omission is allowed only when marked optional. connectorstringNo Passed using this declared shape; omission is allowed only when marked optional. connecterstringNo Passed using this declared shape; omission is allowed only when marked optional. optionsRecord<string, unknown>No Passed using this declared shape; omission is allowed only when marked optional.
ZeruxStructureConfig# Option Accepted TypeScript value Required Meaning appstringNo Passed using this declared shape; omission is allowed only when marked optional. middlewarestring | string[]No Passed using this declared shape; omission is allowed only when marked optional. controllersstring | string[]No Passed using this declared shape; omission is allowed only when marked optional. composablesstring | string[]No Passed using this declared shape; omission is allowed only when marked optional. pluginsstring | string[]No Passed using this declared shape; omission is allowed only when marked optional. publicstring | string[]No Passed using this declared shape; omission is allowed only when marked optional. envstring | string[]No Passed using this declared shape; omission is allowed only when marked optional.
ZeruxServerConfig# Option Accepted TypeScript value Required Meaning portnumberNo Passed using this declared shape; omission is allowed only when marked optional. devPortnumberNo Passed using this declared shape; omission is allowed only when marked optional. allowedDomainsstring | string[]No Passed using this declared shape; omission is allowed only when marked optional. allowedDevDomainstringNo Passed using this declared shape; omission is allowed only when marked optional.
Option Accepted TypeScript value Required Meaning modulesArray<string | ZeruxDevtoolsModuleConfig>No Passed using this declared shape; omission is allowed only when marked optional.
Option Accepted TypeScript value Required Meaning packagestringYes Passed using this declared shape; omission is allowed only when marked optional. enabledbooleanNo Passed using this declared shape; omission is allowed only when marked optional. optionsRecord<string, unknown>No Passed using this declared shape; omission is allowed only when marked optional.
ZeruxWorkerConfig# Option Accepted TypeScript value Required Meaning minThreadsnumberNo Passed using this declared shape; omission is allowed only when marked optional. maxThreadsnumberNo Passed using this declared shape; omission is allowed only when marked optional.
SecurityConfig# Option Accepted TypeScript value Required Meaning keysSecuritySaltsAndKeysNo Passed using this declared shape; omission is allowed only when marked optional. saltsSecuritySaltsAndKeysNo Passed using this declared shape; omission is allowed only when marked optional.
AuthConfig# Option Accepted TypeScript value Required Meaning
Additional configuration chapters#