React global configuration

Purpose

Provide what is essentially an explicitly set of frozen global variables which can then be required by any module that needs them.

This can be preferable to having to pass any configuration all the way through your node application, or put your configuration inside state of component. This method is usually better than setting global variables.

Installation

$ npm install react-global-configuration

API

set( configuration, [options] )

import config from 'react-global-configuration';

config.set({ qux: 'corge', garply: 'fred' }, { freeze: false, environment: 'test' });
config.set({ qux: 'grault' }, { freeze: false, environment: 'production' });
config.set({ 
    foo: 'bar',
    bar: {
        baz: 'qux'
    },
    baz: ['qux'],
    qux: 'quux',
    garply: 'waldo'
});

Sets a configuration.

• configuration - whatever you want to be made available when subsequently importing / requiring get function react-global-configuration.
• options - object optionally containing the following:
  • options.freeze default: true - used to prevent the freezing of the configuration object.
  • options.assign default: false - causes the passed configuration object to have its properties assigned to the existing configuration, rather than replacing it.
  • options.environment default: 'global' - used to define the environment for the passed configuration.

setEnvironment( environment )

import config from 'react-global-configuration';

config.setEnvironment('production');

Defines the current environment in order to obtain the appropriate configurations.

• environment - key to define the current environment of the application. This setting is used after in get() function to obtain the appropriate setting.

get( [key], [default] )

import config from 'react-global-configuration';

config.get('foo'); //'bar'
config.get('bar'); //{ baz: 'qux' }
config.get('bar.baz'); //'qux'
config.get('baz'); //['qux']
config.get('baz.0'); //'qux'
config.get('qux'); //'grault' -> environment value
config.get('garply'); //'waldo' -> global value

Obtains a specific configuration.

• key - key to the setting you want to recover. If you do not put this key you recover all settings.
• default - default value if not exists the setting with the specified key. If you do not put this parameter you get null value by default.

serialize( [environment] )

import config from 'react-global-configuration';

config.serialize(); //"{foo:'bar',bar:{baz:'qux'},baz:['qux'],qux:'quux',garply:'waldo'}"
config.serialize('test'); //"{qux:'corge',garply:'fred'}"
config.serialize('production'); //"{qux:'grault'}"

Serialize configuration to a superset of JSON.

• environment default: 'global' - key to define the environment configuration you wants to serialize.

reset()

import reset from 'react-global-configuration/reset';

reset();

This is a testing utility that removes the existing configuration from the require cache. By calling this, calling config.set(configuration) and then re-requiring any target file, that target file will then be returned from require with the new configuration applied.

Example Usage

Server Side

config.js (global configuration file)

const config = {
    foo: 'bar' 
};

export default config;

server.js (initiation of server side process)

import config from 'react-global-configuration';
import configuration from './config';
import App from './app';

config.set(configuration);

new App();

render.js (render of server side process)

import config from 'react-global-configuration';

export renderScripts = () => 
    `
        <script>
            window.__INITIAL_CONFIG__ = ${config.serialize()};
        </script>
    `;

Client Side

client.js (initiation of client side js, assume compiled via browserify / webpack / similar)

import React from 'react';
import config from 'react-global-configuration';
import App from './app';

(function clientJS() {
    config.set(window.__INITIAL_CONFIG__);
    React.render(<App/>, document);
}());

React

component.js (somewhere inside the client side app)

import React from 'react';
import config from 'react-global-configuration';

class Component extends React.Component {
    render() {
        return (
            <div>{ config.get('foo') }</div>
        );
    }
};

export default Component;

Testing

gulp/test.js

import gulp from 'gulp';
import mocha from 'gulp-mocha';
import config from 'react-global-configuration';

config.set({ foo: 'baz' }, { freeze: false });

gulp.task('test', function gulpTest() {
    return (
        gulp
            .src([ 'app/**.test.*' ], { read: false })
            .pipe(mocha())
    );
});

appLogic.test.js

import reset from 'react-global-configuration/reset';
import assert from 'assert';

describe('appLogic', () => {
    it('should return foo from configuration', () => {
        import config from 'react-global-configuration';
    
        const foos = [ 'alpha', 'beta', 'gamma' ];
        foos.forEach((foo) => {
            // This only works because `freeze: false` was set the first time set was called (in gulp/test.js).
            config.set({ foo: foo });
            const appLogic = require('./appLogic');
            assert(appLogic() === foo);
        });
    });

    afterEach(() => {
        reset();
    });
});

Contributions

Issues and pull requests are most welcome.

Thanks

React global configuration was initially inspired by global-configuration. Many thanks to Josh-a-e.

License

MIT