Configuration

Layers of Configuration
There are three layers of configuration available in your Masquerade project, each with a different focus and scope.
​
Env
Config
Stage
Scope
Environment
Application
Application
Security
Sensitive
Public
Public
Source
/.env
/app/config/
/app/app.ts
Validated
Yes
No
No
Access
Global
Global
Boot
Env module
The Env module pulls settings from your machines existing process.env and project .env file and parses them according to a schema. 
The purpose of your .env file is to introduce environment specific variables that may change between deployments and store sensitive data such as api keys.
Never commit your .env file to a public repository. Your schema should inform the application of any defaults, but if you really need to provide a sample .env file, name it .env.example and be certain to remove all sensitive information.
We use the Zod library to create and parse schemas in the application due to it's first-class TypeScript support and ability to infer the shape of the schema into a type.
You can modify this schema via the /app/schemas/env-schema.ts file to change default values and validation logic. You can read more about how to define a schema in the Validation section.
The shape of this schema is used as the Contract for the Env module.
The EnvProvider service provider should always be the first provider loaded in your application.
An example .env file:
1
# Environment
2
NODE_ENV=development
3
PLATFORM=darwin # Mac
4
​
5
# Logging
6
LOG_LEVEL=debug # Show all cli output
7
​
8
# Database
9
DB_PROVIDER=sqlite3 # Use a local sqlite flatfile database
10
DB_URL=file:./database.db
11
DB_DATABASE=masquerade
12
​
13
# Browsers
14
# Example of setting a non-standard browser executable path:
15
CHROME_DARWIN_PATH="/Applications/ALTERNATE_DIRECTORY/Microsoft\ Edge\ Canary.app/Contents/MacOS/Microsoft\ Edge\ Canary" 
16
​
17
# Services
18
BUGSPLAT_KEY=<.....>
Copied!
Config module
The Config module allows you to define static settings that can be augmented with parsed data from the Env module. 
Where the Env module is a flat Key / Value store, you Config can have any shape you need and include simple data generation functions if required.  
To define a new Configuration module create a file in the /app/config path such as /app/config/foo-config.ts 
Creating a new configuration
You can use the make:config command in your CLI to scaffold a new configuration quickly, however to demonstrate the flow, we've included an example of how to create one manually.
Define Contract Shape
/app/contracts/config.ts
1
/**
2
 * ... other config types ...
3
 */
4
export interface FooConfigurationContract extends ConfigurationContract {
5
  hello: string
6
}
7
​
Copied!
Define Configuration
/app/config/foo-config.ts
1
export class FooConfiguration
2
  extends Configuration
3
  implements FooConfigurationContract {
4
    public hello = this.env.get("HELLO_STRING", "world")
5
  }
Copied!
Add to ConfigProvider
/app/providers/config-provider.ts
1
export class ConfigProvider extends Provider {
2
  protected config(): ConfigContract {
3
    return new Config({
4
      /*
5
       * Required Configurations...
6
       */
7
      automation: new AutomationConfiguration(),
8
      browsers: new BrowsersConfiguration(),
9
      ua: new UserAgentConfiguration(),
10
      auditions: new AuditionsConfiguration(),
11
      commands: new CommandsConfiguration(),
12
      
13
      /*
14
       * Add your new configuration here!
15
       */ 
16
      foo: new FooConfiguration(),
17
    })
18
  }
19
}
Copied!
Stage module
The purpose of the Stage module is to bootstrap your application when a command is called. It achieves this through an init hook which you can find in /app/hooks/init/app.ts 
The Stage defines the providers to load, as well as other scripts to call at runtime.
Although the State is instantiated in the Hook, the primary configuration options are set in the root /app/app.ts file.
1
/**
2
 * Define the providers required by the application.
3
 * Note that the order of the providers is important.
4
 * @type {StageOptions}
5
 */
6
export const options: StageOptions = {
7
  providers: [
8
    /*
9
     * Core Service Providers...
10
     */
11
    EnvProvider,
12
    ConfigProvider,
13
​
14
    /*
15
     * Framework Service Providers...
16
     */
17
    AutomationProvider,
18
    BrowserProvider,
19
    AuditionProvider,
20
​
21
    /*
22
     * Application Service Providers...
23
     */
24
    ActProvider,
25
    DatabaseProvider,
26
    
27
    // Add any custom or third-party providers here:
28
    
29
    FooPluginProvider,
30
  ],
31
}
Copied!
​

Getting Started - Previous

Installation

Next - Getting Started

Directory Structure

Last modified 1yr ago

Copy link

Contents

Layers of Configuration

Env module

Config module

Creating a new configuration

Stage module