angular-environment-config

Hostname based environment configuration module for AngularJS

Contents

• Installation
• Usage
• Example
• API
  • $appEnvironmentProvider
  • $appEnvironment

Get it

• Download the source (minified);
• Install using npm: run $ npm i angular-environment-config from your console; or
• Install using bower: run $ bower install angular-environment-config from your console

Use it

1. Add 'luminous.environment' to your main module's list of dependencies

   angular.module('myWebApp', ['luminous.environment']);

2. Configure your environments during config phase using the $appEnvironmentProvider

   $appEnvironmentProvider
       .addEnvironment('local', ['127.0.0.1', 'localhost', /\.local$/i], {});

3. Set default properties for all environments using $appEnvironmentProvider.setDefaults()

   $appEnvironmentProvider
       .setDefaults({ titlePrefix: '', apiUrl: '/api/' });

4. Access the readonly config variables for the current environment using the $appEnvironment service via the config property.

   $document[0].title = $appEnvironment.config.titlePrefix + 'My App';

Stare intently at this example of it

angular.module('myWebApp', [
    'luminous.environment',
]);

angular.module('myWebApp')
    .config(myWebAppConfig)
    .controller('MainViewController', MainViewController);

myWebAppConfig.$inject = ['$appEnvironmentProvider'];
function myWebAppConfig (  $appEnvironmentProvider){
    
    $appEnvironmentProvider
    
        // Default config for all environments
        .setDefaults({
            titlePrefix: '',
            apiUrl: '/api/',
        })
        
        // Local environment
        // Matches: 127.0.0.1, localhost, or any hostname that ends with .local
        .addEnvironment('local', ['127.0.0.1', 'localhost', /\.local$/i], {
            titlePrefix: 'LOCAL :: ',
            apiUrl: 'http://localhost:7331/',
        })
        
        // Production environment
        // Matches: www.my-app.com, and my-app.com
        .addEnvironment('production', /^(|www\.)my-app.com$/, {
            apiUrl: 'https://api.my-app.com/',
        })
        
        // Set the default environment to Local
        // In case the hostname doesn't match one of the rules above
        .defaultEnvironmentName('local');
    
}

MainViewController.$inject = ['$appEnvironment', '$document'];
function MainViewController (  $appEnvironment,   $document) {
    
    // Set the document title
    
    $document[0].title = $appEnvironment.config.titlePrefix
        + 'My App - Powered by things, that do things!';
    

    // The the local environment will now have the document title:
    //     LOCAL :: My App - Powered by things, that do things!

    // Whereas the live environment will now have the document title:
    //     My App - Powered by things, that do things!

}

---

API

---

Provider

---

$appEnvironmentProvider

---

addEnvironment(environmentName, hostnames, config)

Adds a new environment config -- identified by environmentName -- that will be used when the Angular app's $location.host() matches one of the Strings or RegExps provided in hostnames.

$appEnvironmentProvider
    .addEnvironment('local', ['127.0.0.1', 'localhost', /\.local$/i], {
        // Local environment would match '127.0.0.1', 'localhost', and any
        // hostname that ends with .local
        titlePrefix: 'LOCAL :: ',
        apiUrl: 'http://localhost:7331/',
    })
    .addEnvironment('testing', 'test.my-app.com', {
        // Testing environment would match 'test.my-app.com'
        titlePrefix: 'TESTING :: ',
        apiUrl: 'https://test-api.my-app.com/',
    })
    .addEnvironment('production', /^(www\.|)my-app.com$/i, {
        // Production environment would match 'my-app.com' with or without
        // the leading 'www.', but would not match 'foo.my-app.com'
        apiUrl: 'https://api.my-app.com/',
    });

Arguments

Parameter	Type	Description
environmentName	String	The internal name for this environment (e.g. local)
hostnames	String RegExp Array	Hostname String or RegExp or an Array of such, used to match against $location.host().
config	Object	The environment configuration, to be applied to a new AppEnvironmentConfig on top of any defaults specified via $appEnvironmentProvider.setDefault().

Returns

$appEnvironmentProvider

---

useConfigFor(environmentName).whenHostnameMatches(hostname)

Specify the environmentName to use when the hostname matches hostname.

$appEnvironmentProvider
    .useConfigFor('testing')
        .whenHostnameMatches(/^preview\.[a-z0-9-]{3,}\.my-app.com/i);

Arguments

Parameter	Type	Description
environmentName	String	The internal name of the environment (e.g. local)
hostname	String RegExp	Hostname String or RegExp for matching against $location.host()

Returns

$appEnvironmentProvider

---

defaultEnvironmentName(environmentName)

Specify the environmentName to fall back on when none of the specified environment hostnames match the current hostname.

$appEnvironmentProvider
    .defaultEnvironmentName('local');

Important note: If a default environment name is not specified, and the current hostname does not match a configured host name, the $appEnvironment service will throw an EnvLookupError during init.

Arguments

Parameter	Type	Description
environmentName	String	The internal name of the environment to use when all else fails (e.g. local)

Returns

$appEnvironmentProvider

---

setDefaults(properties)

Set multiple default properties for $appEnvironment.config at once.

$appEnvironmentProvider
    .setDefaults({
        titlePrefix: '',
        apiUrl: '/api/',
    });

Arguments

Parameter	Type	Description
properties	Object	Default properties to add to $appEnvironment.config for all environments.

Returns

$appEnvironmentProvider

---

setDefault(key, value)

Specify a default value for key in $appEnvironment.config

$appEnvironmentProvider
    .setDefault('apiUrl', '/api/');

Arguments

Parameter	Type	Description
key	String	The property name
value	*	The default value

Returns

$appEnvironmentProvider

---

Service

---

$appEnvironment

---

is(environmentName)

Determine if environmentName is the name of the current environment.

if (!$appEnvironment.is('production')) {
    // Logic that will effect all environments except 'production'
}

Arguments

Parameter	Type	Description
environmentName	String	The name of the environment

Returns

Boolean --- true if the current environment name is environmentName, otherwise false.

---

environmentName

String --- The name of the current environment

if ('testing' === $appEnvironment.environmentName) {
    // Logic that will only effect the 'testing' environment
} else {
    // Logic that will effect all environments except 'testing'
}

---

config

AppEnvironmentConfig --- Configuration object for the current environment, values are read-only.

$document[0].title = $appEnvironment.config.titlePrefix + 
    'MyApp - Created by things, for things';

---

hostname

String -- The hostname of the current environment.

if ('localhost' === $appEnvironment.hostname) {
    // Logic that will only occur if the hostname used to identify the current
    // environment was 'localhost'
}

---

isDefault

Boolean --- true if default environment configuration is being used, otherwise false.

if (true === $appEnvironment.isDefault) {
    // Logic that will only occur if the current environment is the environment specified in $appEnvironmentProvider.defaultEnvironmentName()
}