Configuration — Noderyx Documentation

01

How configuration loads

loadEnvironment() reads .env into process.env before anything else runs. noderyx.config.js then converts those strings into typed values and groups them per subsystem. Code reads the config object—never process.env directly.

server.js

import { loadEnvironment } from "noderyx-framework";

loadEnvironment();
const { default: config } = await import("./noderyx.config.js");

NOTE

The dynamic import matters: configuration is evaluated after the environment exists.

02

Typed helpers

Environment variables are always strings. Three helpers convert them without scattering parsing logic through the codebase.

noderyx.config.js

import { envBoolean, envList, envNumber } from "noderyx-framework";

envBoolean("APP_DEBUG", false)      // "true" → true
envNumber("DB_PORT", 3306)          // "3306" → 3306
envList("CORS_ORIGINS")             // "a,b"  → ["a", "b"]

03

Application

Identity, environment, and logging.

NODE_ENV development or production. Production enables caching, compression, HSTS, and hides stack traces.

APP_NAME Human-readable application name.

APP_DEBUG Detailed error pages. Defaults to on outside production.

APP_URL Base URL used by the application.

APP_TIMEZONE / APP_LOCALE Defaults for date and language handling.

LOG_LEVEL Verbosity of server logging.

HOST / PORT Listening address. 0.0.0.0 accepts connections from the network.

04

Public identity and SEO

These values power titles, descriptions, canonical URLs, robots.txt, and sitemap.xml. In production they must be the final HTTPS origin.

.env

SITE_NAME="Your Brand"
SITE_URL=https://www.example.com
SITE_DESCRIPTION="A concise description of the website."

NOTE

SITE_URL must have no trailing slash.

05

Security and sessions

The security block is where most production hardening happens. Defaults are safe; these variables adjust them for your traffic and topology.

APP_KEY Required in production. Signs sessions, cookies, and CSRF tokens.

TRUST_PROXY Only true behind a proxy you control—the header is trivially spoofed.

REQUEST_BODY_LIMIT Maximum request body in bytes. Default 1 MB.

CORS_ORIGINS Comma-separated allowlist. Empty means no cross-origin access.

RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX Requests permitted per address per window.

SESSION_COOKIE / SESSION_MAX_AGE Cookie name and lifetime in seconds.

SESSION_SAME_SITE / SESSION_SECURE Lax by default; Secure automatically in production.

06

Database

DB_TYPE selects which block is used, so all three engines can stay documented in one .env file.

.env

DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=
DB_NAME=my_app
DB_POOL_MAX=10

DATABASE_URL=postgresql://user:password@localhost:5432/my_app
MONGODB_URL=mongodb://localhost:27017

07

Cache

Caching covers view discovery, parsed trees, static reads, and compressed asset variants. Sizes are bounded so a small server does not run out of memory.

CACHE_DRIVER memory by default.

CACHE_PREFIX Namespace for cache keys.

CACHE_TTL Default entry lifetime in seconds.

CACHE_MAX_ITEMS Upper bound on cached entries.

CACHE_STATIC_MAX_AGE Browser cache lifetime for files under /public.

CACHE_STALE_WHILE_REVALIDATE Window in which a stale asset may be served while refreshing.

08

Mail

The log driver is the safe development default: messages are written to the console instead of being sent. SMTP settings are consumed by mail packages.

.env

MAIL_DRIVER=log
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_SECURE=false
MAIL_FROM_ADDRESS=hello@example.com
MAIL_FROM_NAME="Your Brand"

09

AI

AI is off until AI_ENABLED=true, and the provider block selects which credentials are read. The full reference lives on the AI page.

.env

AI_ENABLED=true
AI_PROVIDER=openai
OPENAI_API_KEY=your_server_key
OPENAI_MODEL=gpt-5.6-sol

10

Mobile and native

Device builds read the app identity and the address of your deployed API, because a packaged app has no server of its own.

.env

MOBILE_APP_ID=com.example.myapp
MOBILE_APP_NAME="My App"
MOBILE_API_URL=https://api.example.com

NOTE

The app id must be in reverse-domain form—both app stores require it.

11

Environment discipline

Configuration mistakes cause more production incidents than code does.

.env is git-ignored from the first commit—keep it that way and keep .env.example current.
Give every environment its own APP_KEY, database, and credentials.
Set values through your host's environment settings in production rather than uploading a .env file where possible.
Never expose a secret to a view or a client bundle; if a key reaches a browser, rotate it.
Restart the application after changing .env—values are read at startup.