• Stars
    star
    108
  • Rank 321,259 (Top 7 %)
  • Language
    TypeScript
  • License
    Other
  • Created over 8 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

node.js environment aware application configuration

Electrode Confippet NPM version Build Status

Confippet is a versatile, flexible utility for managing configurations of Node.js applications. It's simple to get started, and can be customized and extended to meet the needs of your app.


Contents

Features

  • Simple - Confippet's presetConfig automatically composes a single config object from multiple files. For most applications, no further customization is necessary.
  • Flexible - Supports JSON, YAML, and JavaScript config files.
  • Powerful - Handles complex multi-instance enterprise deployments.

Getting Started

In this example, we'll create two config files: a default file that always loads, and a production file that loads only when the NODE_ENV environment variable is set to production. We'll then import those files into a standard Node.js app.

Installation

npm install electrode-confippet --save

Basic Use

Make a config/ directory inside the main app directory, and put the following into a file named default.json in that directory:

{
  "settings": {
    "db": {
      "host": "localhost",
      "port": 5432,
      "database": "clients"
    }
  }
}

Next, add another file called production.json to the config/ directory, with this content:

{
  "settings": {
    "db": {
      "host": "prod-db-server"
    }
  }
}

Finally, in our Node.js app, we can import Confippet and use the configuration we've created:

const config = require("electrode-confippet").config;
const db = config.$("settings.db");

In this example, default.json will be loaded in all environments, whereas production.json will be loaded only when the NODE_ENV environment variable is set to production. In that case, the value of host in the db object will be overwritten by the value in production.json.

Config Composition

Confippet's presetConfig composes together files in the config/ directory, in the following order:

This is the same as node-config files.

  1. default.EXT
  2. default-{instance}.EXT
  3. {deployment}.EXT
  4. {deployment}-{instance}.EXT
  5. {short_hostname}.EXT
  6. {short_hostname}-{instance}.EXT
  7. {short_hostname}-{deployment}.EXT
  8. {short_hostname}-{deployment}-{instance}.EXT
  9. {full_hostname}.EXT
  10. {full_hostname}-{instance}.EXT
  11. {full_hostname}-{deployment}.EXT
  12. {full_hostname}-{deployment}-{instance}.EXT
  13. local.EXT
  14. local-{instance}.EXT
  15. local-{deployment}.EXT
  16. local-{deployment}-{instance}.EXT

Where:

  • EXT can be any of ["json", "yaml", "js"]. Confippet will load all of them, in that order. Each time it finds a config file, the values in that file will be loaded and merged into the config store. So js overrides yaml, which overrides json. You can add handlers for other file types and change their loading orderโ€”see composeConfig for further details.
  • {instance} is your app's instance string in multi-instance deployments (specified by the NODE_APP_INSTANCE environment variable).
  • {short_hostname} is your server name up to the first dot.
  • {full_hostname} is your whole server name.
  • {deployment} is your deployment environment (specified by the NODE_ENV environment variable).

Overridden values are handled as follows:

  • Objects are merged.
  • Primitive values (string, boolean, number) are replaced.
  • Arrays are replaced, unless the key starts with + and both the source and the target are arrays. In that case, the two arrays are joined together using Lodash's _.union method.

After Confippet loads all available configuration files, it will look for override JSON strings from the NODE_CONFIG and CONFIPPET* environment variables. See the next section for details.

Environment Variables

Confippet reads the following environment variables when composing a config store:

  • AUTO_LOAD_CONFIG_OFF - If this is set, then Confippet will not automatically load any configuration into the preset config store. Confippet.config will be an empty store. This enables you to customize the config structure before loading.
  • NODE_CONFIG_DIR - Set the directory to search for config files. By default, Confippet looks in the config directory for config files.
  • NODE_ENV - By default, Confippet loads development config files after loading default. Set this environment variable to change to a different deployment, such as production.
  • NODE_APP_INSTANCE - If your app is deployed to multiple instances, you can set this to load instance-specific configurations.
  • AUTO_LOAD_CONFIG_PROCESS_OFF - By default, after composing the config from all sources, Confippet will use processConfig to process templates. You can set this environment variable to disable template processing.
  • NODE_CONFIG - You can set this to a valid JSON string and Confippet will parse it to override the configuration.
  • CONFIPPET* - Any environment variables that starts with CONFIPPET will be parsed as JSON strings to override the configuration.

Using Templates

Values in your config files can be templates, which will be resolved with a preset context. See processConfig for more information about how to use config value templates.

Usage in Node Modules

If you have a Node.js module that has its own configurations based on environment variables, like NODE_ENV, you can use Confippet to load config files for your module.

The example below will use the default compose options to compose configurations from the directory config under the script's directory (__dirname).

const Confippet = require("electrode-confippet");

const options = {
  dirs: [Path.join(__dirname, "config")],
  warnMissing: false,
  context: {
    deployment: process.env.NODE_ENV
  }
};

const defaults = {
  foo: "bar"
};

const config = Confippet.loadConfig(options, defaults /* refresh: true */);

Customization

The composeConfig feature supports a fully customizable and extendable config structure. Even Confippet's own preset config structure can be extended, since it's composed using the same feature.

If you want to use the preset config, but add an extension handler or insert a source, you can turn off auto loading, and load it yourself with your own options.

NOTE: This has to happen before any other file accesses Confippet.config. You should do this in your startup index.js file.

For example:

process.env.AUTO_LOAD_CONFIG_OFF = true;

const JSON5 = require("json5");
const fs = require("fs");
const Confippet = require("electrode-confippet");
const config = Confippet.config;

const extHandlers = Confippet.extHandlers;
extHandlers.json5 = (fullF) => JSON5.parse(fs.readFileSync(fullF, "utf8"));

Confippet.presetConfig.load(config, {
  extSearch: ["json", "json5", "yaml", "js"],
  extHandlers,
  providers: {
    customConfig: {
      name: "{{env.CUSTOM_CONFIG_SOURCE}}",
      order: 300,
      type: Confippet.providerTypes.required
    }
  }
});

The above compose option adds a new provider that looks for a file named by the environment variable CUSTOM_CONFIG_SOURCE and will be loaded after all default sources are loaded (controlled by order).

It also adds a new extension handler, json5, to be loaded after json.

To further understand the _$ and the compose options, please see the documentation for store, composeConfig, and processConfig.

Built with โค๏ธ by Team Electrode @WalmartLabs.

More Repositories

1

electrode

Web applications with node.js and React
HTML
2,101
star
2

electrode-native

A platform to ease integration&delivery of React Native apps in existing mobile applications
TypeScript
725
star
3

electrode-io.github.io

The public website of the Electrode platform
HTML
336
star
4

electrode-react-ssr-caching

Optimize React SSR with profiling and component caching
JavaScript
316
star
5

electrode-explorer

An Electrode application that showcases all of your components in a live demo
JavaScript
254
star
6

electrode-electrify

Electrify is an webpack visualizer for analyzing webpack bundles.
JavaScript
230
star
7

electrode-server

Electrode's configurable web server using Hapi.js atop Node.js
JavaScript
224
star
8

electrode-ota-server

Electrode Over The Air Server for hot deployment of React Native and Cordova mobile apps
JavaScript
204
star
9

electrode-csrf-jwt

Stateless Cross-Site Request Forgery (CSRF) protection with JWT
JavaScript
126
star
10

above-the-fold-only-server-render

An Electrode component for optionally skipping server side render of components outside of Above the fold
JavaScript
117
star
11

isomorphic-loader

Webpack isomorphic loader tools to make Node require handle files like images for Server Side Rendering (SSR)
JavaScript
68
star
12

electrode-archetype-njs-module-dev

A WalmartLabs flavored NodeJS Module archetype
JavaScript
67
star
13

electrode-bundle-analyzer

Analyze your webpack deduped and minified bundle JS file.
JavaScript
66
star
14

electrode-webpack-reporter

A HTML based reporter for webpack dev server
JavaScript
59
star
15

electrode-gulp-helper

Helper functions for using gulp
JavaScript
59
star
16

electrode-check-dependencies

An Electrode module to verify component dependencies against a list
JavaScript
58
star
17

electrode-docgen

A custom metadata extractor and documentation generator for the Electrode framework
JavaScript
57
star
18

fynpo

๐Ÿ› ๏ธ๐Ÿ“ฆ a node.js monorepo manager
JavaScript
55
star
19

electrode-static-paths

Electrode server decor to serve static files
JavaScript
55
star
20

react-native-electrode-bridge

Electrode Native - Bridge
Java
44
star
21

xarc-run

npm run scripts concurrently and serially, and more.
JavaScript
42
star
22

memcache

Node.js memcached client with the most efficient ASCII protocol parser
TypeScript
37
star
23

electrode-ota-desktop

Electrode OTA Desktop Client
JavaScript
22
star
24

electrode-ota-ui

[Deprecated for electrode-ota-server/electrode-ota-ui] Electrode OTA Web/Client UI
JavaScript
17
star
25

ern-navigation

Electrode Native solution for React Native navigation
JavaScript
12
star
26

movies-reloaded-miniapp

Our new movie miniapp built on the Electrode Native Navigation.
JavaScript
10
star
27

car-buying-instructions

JavaScript
9
star
28

movielist-miniapp

Electrode Native - Movie List MiniApp (Getting Started)
Objective-C
8
star
29

fastify-server

Electrode using Fastify
TypeScript
6
star
30

moviedetails-miniapp

Electrode Native - Movie Details MiniApp (Getting Started)
JavaScript
6
star
31

electrode-keepalive

node.js HTTP agent with customized keep alive
JavaScript
6
star
32

kax

TypeScript
5
star
33

react-native-livebundle

LiveBundle Native Module
Java
3
star
34

livebundle

LiveBundle CLI
TypeScript
3
star
35

electrode-native-starter-manifest

Electrode Native - Starter Manifest
3
star
36

react-native-ernnavigation-api

Electrode Native - Navigation API (Getting Started)
Swift
3
star
37

electrode-native-manifest

Electrode Native - Master Manifest
Java
3
star
38

electrode-native-showcaseapp-android

Native application that showcases electrode native MiniApps and APIs.
Java
2
star
39

electrode-native-sample-cauldron

Sample Electrode Native Cauldron
2
star
40

fynpo-old

Supplement tools for using fyn with lerna
JavaScript
2
star
41

car-buying-service

mock service for car buying app
JavaScript
2
star
42

car-buying

A sample car buying app
JavaScript
2
star
43

ern-bundle-store

Electrode Native Bundle Store Server
TypeScript
2
star
44

electrode-native-website

The site and docs for Electrode Native
JavaScript
2
star
45

react-native-ernmovie-api

Electrode Native - Movie API (Getting Started)
Swift
2
star
46

ernnavigation-api-impl-native

Native implementation of ernnavigation-api
Objective-C
2
star
47

electrode-demo-app

Demo application generated by Electrode platform unmodified
JavaScript
1
star
48

react-native-ernmovie-api-impl

Objective-C
1
star
49

ern-sourcemap-store

Electrode Native sourcemap store server
TypeScript
1
star
50

electrode-native-binarystore

Electrode Native - Binary Store
JavaScript
1
star
51

ern-container-transformer-xcframework

Electrode Native XCFramework Container Transformer
Shell
1
star
52

ern-container-publisher-maven

Electrode Native Maven Container Publisher
TypeScript
1
star
53

resolve-alias

set virtual module aliases for resolve and require
JavaScript
1
star
54

ern-base-composite-starter

Electrode Native Base Composite Starter
JavaScript
1
star
55

electrode-native-showcaseapp-ios

Swift
1
star
56

react-native-ernmovie-api-impl-js

JavaScript
1
star