3.1.0 • Public • Published


    Build Status Greenkeeper badge npm

    A simple configuration manager for typescript based projects.

    Table of contents

    1. Usage
    2. Usage with webpack
    3. Configuration
      1. Using Files
      2. Using Environment Variables
      3. Using Commandline Params
      4. Custom Config Directory
    4. Differences With Node Config


    IMPORTANT: Make sure you have a local tsconfig.json file in your project.

    1. Install package

      npm i node-config-ts
    2. Add a postinstall step in package.json

        "scripts": {
          "postinstall": "node-config-ts"
    3. Create a config directory inside your project's root folder and add a default.json file. A typical folder structure looks as follows —

      └── config/
          └── default.json

      default.json should contain your application's configuration

    4. Create typings

      npm install

      A new Config.d.ts will be generated automatically. This file could be ignored from git as it gets automatically generated based on the structure of default.json

    5. Import and use node-config-ts

      import {config} from 'node-config-ts'
      console.log(config) // logs the config data from default.json

    Usage With Webpack

    If your project uses webpack then with the NodeConfigTSPlugin you can easily make your application run in the browser without any change.


    import {NodeConfigTSPlugin} from 'node-config-ts/webpack'
    export = NodeConfigTSPlugin({
      // .. other stuff
      entry: './src/index.js',
      output: {
        path: path.resolve(__dirname, 'dist'),
        filename: 'bundle.js'


    The configs are merged in the following order of priority —

    1. Commandline params
    2. Environment variable
    3. User specific config file
    4. Deployment specific config file
    5. Environment specific config file

    Using files

    Configurations are loaded via config files that are written in JSON format for now. A typical project looks like this —

    └── config/
        ├── Config.d.ts
        ├── default.json
        ├── deployment/
        │   ├──
        │   ├──
        │   └──
        ├── env/
        │   └── production.json
        └── user/
            ├── ec2-user.json
            ├── andy.json
            └── sara.json

    There are three directories in which a project can have configurations — deployment, env and user. These directories can have multiple files inside them and based on the environment variables an appropriate config file is selected for overriding the base default.json. For example if the NODE_ENV variable is set to production the env/production.json configuration will be merged with default.json and override default values with its own. Similarly if DEPLOYMENT env variable is set to then deployment/ is merged with the other configs. Here is a table for environment to directory mapping —

    process.env directory
    NODE_ENV or NODE_CONFIG_TS_ENV /config/env
    DEPLOYMENT /config/deployment
    USER (USERNAME) /config/user

    User specific configuration is loaded based on USER env variable (UNIX way) or USERNAME env variable (Windows way).

    You can use NODE_CONFIG_TS_ENV as an alternative to NODE_ENV.

    Using environment variables

    Whenever the value is prefixed with the letters @@ node-config-ts automatically looks for an environment variable with that name. For example —

    // default.json
      "port": "@@APP_PORT"

    In the above case automatically the value of port is set to the value that's available inside the environment variable PORT.

    export APP_PORT=3000
    node server.js // server started with config.port as 3000

    Custom Config Directory

    By default the base directory for loading configs is config. This can be configured using the ENV variable NODE_CONFIG_TS_DIR.

    Using Config type

    Sometimes it's necessary to access the config type info. This can be done via importing Config.

    import {config, Config} from 'node-config-ts'
    const main = (c: Config) => {
      /// ...

    Using commandline params

    The command line arguments can override all the configuration params. This is useful when you want to start a node server by passing the port externally —

    node server.js --port 3000

    In the above case even if the default.json has a port setting of 9000 the cli argument can override it

    // default.json
      "port": 9000

    Differences with node-config

    1. No reserved words: With node-config you can not use a certain set of reserved words in your configuration. This is an unnecessary restriction and node-config-ts doesn't have it.
    2. Simpler API: Instead of using methods such as config.get('xxx') in node-config you can simply use the exported config object.
    3. Warnings & Errors: node-config relies on calling the get and the has methods to issue errors. This is unsafe typically when the configurations are different between your dev and production environments. With node-config-ts you can trust the typescript compiler to issue an error immediately when you try to access a property that isn't defined anywhere. Consider the following case —


      "port": 3000


      "baseURL": "/api"

    In the above case the final configuration should look something like this on john's local machine —

      "port": 3000,
      "baseURL": "/api"
    reading using node-config:
    import config from 'config'
    console.log(config.get('baseURL')) // works locally but fails in production

    This would work when john is running the application on his local machine. But as soon as its deployed in production the configuration property baseURL isn't available anymore and it results in runtime exceptions.

    using node-config-ts:
    import {config} from 'node-config-ts'
    console.log(config.port) // proper intellisense support
    console.log(config.baseURL) // throws compile time error immediately in production

    Because the above object config, is exposed with proper typings, using invalid configurations results in typescript errors. This would happen on both — john's computer and the production server.




    npm i node-config-ts

    DownloadsWeekly Downloads






    Unpacked Size

    17 kB

    Total Files


    Last publish


    • tusharmathur