configuration

introduction

all application configuration lives in two places: the .env file at the project root and the config directory. the .env file holds environment specific values such as secrets and database credentials. the config directory holds structured javascript files that read from the environment and expose typed values to the rest of the application. the framework loads both automatically at boot.

environment file

the .env file sits at the root of your project and contains raw environment variable assignments. you copy the provided .env.example to .env and fill in your values. the .env file is never committed to version control.

1APP_NAME=dframework
2APP_KEY=
3APP_LOCALE=en
4APP_ENV=local
5APP_DEBUG=true
6APP_URL=http://localhost
7APP_PORT=0825
8 
9ANTI_PEEPING=false
10SHIELD_ENABLED=false
11SESSION_DRIVER=memory
12 
13QUEUE_MAX_WORKERS=4
14OPTIMIZE_CSS=true
15 
16DB_HOST=localhost
17DB_USER=root
18DB_PASS=
19DB_NAME=dframework

the framework parses this file on startup. string values of true and false are cast to booleans. numeric strings are cast to numbers. values are immediately available via Env.value() throughout your config files.

config files

each file in the config directory exports a default plain object and uses Env.value() to pull values from the environment. the filename becomes the configuration namespace used for all dot notation lookups throughout the application.

config/app.js

the primary configuration file defines the core runtime behavior of the application.

1// config/app.js
2import { Env } from 'dframework';
3 
4export default {
5  name: Env.value('APP_NAME', 'dframework'),
6  env: Env.value('APP_ENV', 'production'),
7  debug: Env.value('APP_DEBUG', false),
8  url: Env.value('APP_URL', 'http://localhost'),
9  port: Env.value('APP_PORT', 825),
10  locale: Env.value('APP_LOCALE', 'en'),
11  key: Env.value('APP_KEY'),
12 
13  shield: Env.value('SHIELD_ENABLED', true),
14  session_driver: Env.value('SESSION_DRIVER', 'memory'),
15 
16  css: {
17    optimize: Env.value('OPTIMIZE_CSS', true),
18  },
19 
20  queue: {
21    maxWorkers: Env.value('QUEUE_MAX_WORKERS', 4),
22  },
23 
24  database: {
25    host: Env.value('DB_HOST', 'localhost'),
26    user: Env.value('DB_USER', 'root'),
27    pass: Env.value('DB_PASS', ''),
28    name: Env.value('DB_NAME', 'dframework'),
29  },
30};

the env value must be either local or production. any other value will default to production. the debug flag is only active when env is local. the key value is used for session signing and route compilation fingerprinting and should be a long unique secret.

config/auth.js

the authentication config registers the model the framework uses to resolve authenticated users. by default it points to the User model.

1// config/auth.js
2export default {
3  model: 'User'
4};

config/native.js

the native config defines everything related to building your application for native mobile and desktop targets. this file is loaded by the cli kernel in addition to config/app.js.

1// config/native.js
2export default {
3  name: null,
4  identifier: 'com.dframework.app',
5  version: '1.0.0',
6  build: 1,
7  icon: { source: 'native/assets/icon.png', background: '#ffffff', padding: 0 },
8  splash: { enabled: true, background: '#0a0a0a', icon: 'native/assets/icon.png' },
9  theme: { statusBar: 'dark', primary: '#d3ac5f', background: '#0a0a0a' },
10  ios: { orientation: 'all', statusBarHidden: false },
11  android: { orientation: 'unspecified', minSdk: 24, targetSdk: 34, permissions: ['INTERNET'] },
12  desktop: { width: 1280, height: 720, resizable: true },
13};

accessing configuration values

dframework provides a global Config facade available in every context. you retrieve values using dot notation where the first segment is the config filename and the remainder is the key path within that file.

1const env = Config.get('app.env');
2const dbName = Config.get('app.database.name');
3const authModel = Config.get('auth.model', 'User');

the second argument to Config.get is an optional fallback returned when the key does not exist. if no fallback is provided and the key is missing the method returns null.

accessing environment values

inside your config files you use Env.value() to read from the parsed .env file. you can also use it anywhere you need a raw environment value without going through the config system.

1import { Env } from 'dframework';
2 
3const port = Env.value('APP_PORT', 825);
4const dbHost = Env.value('DB_HOST', 'localhost');

hot reloading configuration

in the local environment the framework watches the entire config directory for file changes. when you save a config file it is reimported and registered under the same namespace without restarting the server. this allows you to iterate on configuration values during development without interrupting the running process.