@spa-tools/runtime-config

Reference

This reference covers the Runtime Config usage with Typescript (simply ignore all type usage for Vanilla Javascript).

Under the hood, RuntimeConfig is a singleton class that manages initialization and access to your app's runtime configuration.

RuntimeConfig.initialize()

initialize<S, E> is a static method is used to construct the runtime configuration for your app.

The generic S type is used to define the shape of your domain-config (i.e. the actual configuration settings you want to use) and must extend the BaseConfigSettings type.

The generic E is a union type used to define your environment names. If not specified, it will default to 'development' | 'test' | 'production'.

Usage

import { BaseConfigSettings, DomainConfig, RuntimeConfig } from '@spa-tools/runtime-config';

// here we define the environment names for our app
type MyAppEnvironments = 'dev' | 'uat' | 'live';

// here we define the shape of our app's configuration settings, which
// can be anything you desire but must extend BaseConfigSettings
interface MyAppConfigSettings extends BaseConfigSettings<MyAppEnvironments> {
  authClientId: string;
  myAppApiUrl: string;
}

// here we define the app domain-config, which is just all of the settings
// across all environments using actual environment domain names as keys
//
// note that using the correct domain names is critical for the domain-config
//
// if not using TypeScript, simply construct an object with environment-
// specific domain names as keys and any object desired for each value,
// just be sure to include an "environment" property for each as shown
// uniquely set to the respective environment name
const myAppConfigSet: DomainConfig<MyAppConfigSettings> = {
  'myapp.dev.com': {
    environment: 'dev',
    authClientId: 'auth-client-id-dev',
    myAppApiUrl: 'https://api.dev.myapp.com',
  },
  'myapp.uat.com': {
    environment: 'uat',
    authClientId: 'auth-client-id-uat',
    myAppApiUrl: 'https://api.uat.myapp.com',
  },
  'myapp.com': {
    environment: 'live',
    authClientId: 'auth-client-id-prod',
    myAppApiUrl: 'https://api.myapp.com',
  },
  // here we define the local development
  // environment using localhost as the domain
  localhost: {
    environment: 'dev',
    authClientId: 'auth-client-id-dev',
    myAppApiUrl: 'https://api.dev.myapp.com',
  },
};

// here we initialize the runtime config for our app
export const myAppRuntimeConfig = RuntimeConfig.initialize<MyAppConfigSettings, MyAppEnvironments>(myAppConfigSet);

Parameters

Parameter	Type	Required?	Description
domainConfig	DomainConfig<S> or string	yes	The configuration settings for your app. It's either an instance of the DomainConfig<S> type or a serialized string equivalent (i.e. stringified JSON)
options	RuntimeConfigOptions	no	The options for the runtime config initialization process

Return value

The initialize method returns a RuntimeConfig instance.

RuntimeConfig.initializeObf()

initializeObf<S, E> is a static method is used to construct the runtime configuration for your app from an obfuscated domain-config string.

The generic S type is used to define the shape of your domain-config (i.e. the actual configuration settings you want to use) and must extend the BaseConfigSettings type.

The generic E is a union type used to define your environment names. If not specified, it will default to 'development' | 'test' | 'production'.

Usage

import { BaseConfigSettings, DomainConfig, RuntimeConfig } from '@spa-tools/runtime-config';
// depending on your build setup, you may need to import the file differently
import obfuscatedConfigStr from './myapp-config-obf.txt?raw';

// here we define the environment names for our app
type MyAppEnvironments = 'dev' | 'uat' | 'live';

// here we define the shape of our app's configuration settings, which
// can be anything you desire but must extend BaseConfigSettings
interface MyAppConfigSettings extends BaseConfigSettings<MyAppEnvironments> {
  authClientId: string;
  myAppApiUrl: string;
}

// since the initialization method for obfuscated config is async, one approach
// is to export a variable that holds the runtime config instance; this way it
// can be set after initialization is complete and all imported refs to the config
// will update accordingly
export let myAppRuntimeConfig: RuntimConfig<MyAppConfigSettings, MyAppEnvironments>;

// the initializeObf method is async because of the cryptographic operations
// involved, so we wrap with our own async function to initialize
async function initMyObfuscatedConifg() {
  // here we initialize using the obfuscated config file and then
  // assign it to the module-level variable for use throughout the app
  myAppRuntimeConfig = await RuntimeConfig.initializeObf<MyAppConfigSettings, MyAppEnvironments>(obfuscatedConfigStr);

  console.log('My app runtime config:', myAppRuntimeConfig);
}

// make it happen
initMyObfuscatedConifg();

Parameters

Parameter	Type	Required?	Description
obfuscatedConfig	string	yes	The obfuscated domain config
options	RuntimeConfigOptions	no	The options for the runtime config initialization process

Return value

The initializeObf method returns a promise that resolves to a RuntimeConfig instance.

RuntimeConfig.settings

settings is an instance property of RuntimeConfig that provides access to runtime configuration for the active environment.

// we can access our app's configuration object via the settings
// property and the correct environment settings will be returned
// based on the hostname that is present in the user's browser URL
console.log(
  `App API URL for ${myAppRuntimeConfig.settings.environment} env is ${myAppRuntimeConfig.settings.myAppApiUrl}`
);

RuntimeConfig.hostname

hostname is an instance property of RuntimeConfig that returns the active hostname that is driving the runtime config's current settings.

RuntimeConfig.isRunningLocal

isRunningLocal is an instance property of RuntimeConfig that returns a boolean indicating whether the runtime config is running in a local development environment.

BaseConfigSettings

BaseConfigSettings<E> is the base interface that all config-sets must extend.

The generic E is a string union type used to define environment names, defaulting to 'development' | 'test' | 'production'.

Property	Type	Required?	Default	Comments
environment	E	yes	-	Indicates the environment that respective config settings belong to.

DomainConfig

DomainConfig<S> is a Record<string, S> type that represents a complete domain-config for all environments where the string key is the respective environment hostname (i.e. domain).

The generic S is the shape of the configuration settings and must extend the BaseConfigSettings type.

RuntimeConfigOptions

RuntimeConfigOptions is an interface that defines the options for the runtime config initialization process.

Property	Type	Required?	Default	Comments
locahostIpAddress	string	no	'127.0.0.1'	The IP address to use to detect the local development environment.
manualActiveHostname	string	no	''	The hostname to use to manually set the active config environment. This only needs to be specified when running in a non-browser environment (i.e. SSR)
startsWithMatching	boolean	no	false	Whether to include path with the hostname and use a starts-with matching strategy. By default, the hostname must match exactly; this option supports use cases where only one domain is used and the paths distinguish your environments.

Obfuscation (CLI)

@spa-tools/runtime-config-obf

The @spa-tools/runtime-config-obf CLI command is used to obfuscate and deobfuscate your app's runtime configuration settings.

For obfuscation usage scenario and reasoning, see the Obfuscation Guide.

Argument	Required?	Description
obf or deobf	yes	The command to run (obf = obfuscate and deobf = deobfuscate)
input	yes	The path to the input file
output	no	The path to the output file. If not specified, then the resulting config (obfuscated or deobfuscated) will be output to the console

obfuscate

npx @spa-tools/runtime-config obf ./path/to/static-config.json ./path/to/obfuscated-config.txt

deobfuscate

npx @spa-tools/runtime-config deobf ./path/to/obfuscated-config.txt ./path/to/static-config.json

Obfuscation (NodeJS)

For obfuscation usage scenario and reasoning, see the Obfuscation Guide.

nodejsObfuscateConfig()

The nodejsObfuscateConfig function is used to obfuscate a domain-config within a NodeJS program; it returns the obfuscated config as a string and optionally outputs it to a file.

Parameter	Type	Required?	Default	Comments
domainConfig	DomainConfig	yes	-	A RuntimeConfig domain-config
outputPath	string	no	-	The path to the output file

Usage

import { nodejsObfuscateConfig } from '@spa-tools/runtime-config';
import { myAppConfig } from './myapp-config';

const obfuscatedConfig = nodejsObfuscateConfig(myAppConfig, './path/to/obfuscated-config.txt');
console.log('Obfuscated config:');
console.log(obfuscatedConfig);

nodejsDeobfuscateConfig()

The nodejsDeobfuscateConfig function is used to deobfuscate a domain-config within a NodeJS program; it returns the deobfuscated config as a DomainConfig and optionally outputs it to a file.

Parameter	Type	Required?	Default	Comments
obfuscatedConfig	string	yes	-	The obfuscated config string
outputPath	string	no	-	The path to the output file

Usage

import { nodejsDeobfuscateConfig } from '@spa-tools/runtime-config';

const deobfuscatedConfig = nodejsDeobfuscateConfig(obfuscatedConfig, './path/to/static-config.json');
console.log('Deobfuscated config:', deobfuscatedConfig);