Project structure and environment configuration

Choose discovery directories, output paths and environment loading without ambiguous config files.

A complete structure example#

import type { ZeruxConfig } from 'zeruxjs';
export default {
  type: 'fix', entryPoint: 'index', outDir: '.zerux',
  structure: {
    app: 'app', middleware: ['middleware'], controllers: ['controllers'],
    composables: ['composables'], plugins: ['plugins'], public: ['public'],
    env: ['.env.services'],
  },
} satisfies ZeruxConfig;

Paths resolve relative to the application root. Keep generated output disjoint from source, uploaded files and secrets. outDir selects runtime output; it does not configure this documentation site's static dist/ exporter. The framework compiler enforces output safety rather than treating any supplied path as disposable.

Defaults and accepted forms#

Without overrides the runtime looks in app, middleware, controllers, composables, plugins and public; the entry module basename is index. Directory settings other than app accept a string or string array and are normalized/deduplicated. Use a named directory per concern instead of overloading public assets with application modules.

type is fix, dynamic or function, defaulting to fix. These are runtime structure modes, not React rendering modes or static-export switches. Only choose another mode after reviewing its application-discovery behavior. multisite: true separately enables host/path mapping registration; it does not isolate databases or authenticate tenants.

Environment loading order#

The server command loads .env, .env.local, the selected environment file and its local override before evaluating config. The selected environment uses NODE_ENV when provided, otherwise the startup mode's default. Additional structure.env files are resolved only after the config has been evaluated, so do not expect them to supply values already read at module top level.

Build and standalone scripts do not necessarily use the server startup loader. Provide required deployment environment variables in the process environment, and treat all values as potentially missing strings. Configuration files are executable modules; validate numbers, required credentials and adapter choices at the owning startup boundary. Never copy private environment files into public to make a build work.

JavaScript equivalent#

Use the same object as a default export in zerux.config.js for an ESM application. Add /** @type {import('zeruxjs').ZeruxConfig} */ for editor help. Keep only one active config file; .ts takes precedence over .js, then .mjs, then .cjs. The files are not merged.

Production structure#

Development discovers sources with the framework loader. Production start resolves the built structure and generated metadata. Build first; do not infer that a working development route proves the compiled layout includes that file. Verify source maps, public assets, plugins and application modules in the production output, then start the compiled application from its intended root.

If a route disappears, check the relative app path, supported file conventions, ignored/build directories, filename casing and whether a stale higher-priority configuration file is loaded. A file under public is directly exposed; a file under controllers is reusable code, not automatically a public HTTP route.

Exact option shapes#

The fields below come from the current source declarations. Optional is not a default value. A callback is application code, not a string naming a role.

ZeruxStructureConfig#