grunt-extend

Extends JavaScript Objects and JSON files with other JSON files, and writes them to a new JSON file.

grunt-extend

Extends JavaScript Objects and JSON files with other JSON files, and writes them to a new JSON file

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-extend --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-extend');

This task extends JavaScript Objects and JSON files with other JSON files, using Lo-Dash _.extend() and _.merge() internally. Once the final object is created, the resulting object is written to a new JSON file.

Possible uses include:

  • projects that generate multiple clients
  • projects that share configuration values across multiple clients
  • sharing base configuration values across environments

In your project's Gruntfile, add a section named extend to the data object passed into grunt.initConfig().

grunt.initConfig({
  extend: {
    options: {
      // Task-specific options go here. 
    },
    your_target: {
      // Target-specific file lists and/or options go here. 
    },
  },
})

Type: Object Default value: {}

A JavaScript Object used as the base object in the extension chain. Setting options.defaults as a property of the task will make all of the targets share the same default options. Setting options.defaults inside a target will override the task's default options for that target.

The basic usage example is using an empty object as the default options and write it to a JSON file:

grunt.initConfig({
  extend: {
    options: {
      defaults: {}
    },
    empty: {
      files: {
        'tmp/config-empty.json': []
      }
    }
  }
});

This example uses the default options specified in options.defaults and writes them to a JSON file:

grunt.initConfig({
  extend: {
    options: {
      defaults: {
        coffee: true,
        options: ['a', 'b', 'c']
      }
    },
    defaultConfig: {
      files: {
        'tmp/config-default.json': []
      }
    }
  }
});

It is possible to extend the default options with one or more JSON files, and write the results to a new JSON file:

grunt.initConfig({
  extend: {
    options: {
      defaults: {
        coffee: true,
        options: ['a', 'b', 'c']
      }
    },
    extendedConfig: {
      files: {
        'tmp/config-base.json': ['.config-base.json']
      }
    }
  }
});

Extend is a mult-task, so you can specify multiple targets. Default options can be overridden in individual targets:

grunt.initConfig({
  extend: {
    options: {
      defaults: {
        coffee: true,
        options: ['a', 'b', 'c']
      }
    },
    empty: {
      options: {
        defaults: {}
      },
      files: {
        'tmp/config-empty.json': []
      }
    },
    defaultConfig: {
      files: {
        'tmp/config-default.json': []
      }
    },
    extendedConfig: {
      files: {
        'tmp/config-base.json': ['.config-base.json']
      }
    },
    multipleExtensions: {
      files: {
        'tmp/config-local.json': ['.config-base.json', '.config-local.json']
      }
    }
  }
});

It is also possible to generate multiple files using a single target:

grunt.initConfig({
  extend: {
    options: {
      defaults: {
        coffee: true,
        options: ['a', 'b', 'c']
      }
    },
    allEnvironments: {
      files: {
        'tmp/config-default.json': [],
        'tmp/config-base.json': ['.config-base.json'],
        'tmp/config-local.json': ['.config-base.json', '.config-local.json']
      }
    }
  }
});

In order to extend and object deeply, add deep to the targets options:

grunt.initConfig({
  extend: {
    options: {
      deep: true,
      defaults: {
        coffee: true,
        options: ['a', 'b', 'c']
      }
    },
    extendedConfig: {
      files: {
        'tmp/config-base.json': ['.config-base.json']
      }
    }
  }
});

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

  • 2013-09-38 v0.4.2 Fixing error in documentation.
  • 2013-08-13 v0.4.1 Removing jQuery as a dependency.
  • 2013-08-07 v0.3.0 Support for deep extends.
  • 2013-08-03 v0.2.1 Initial release.
  • 2013-08-03 v0.2.0 Initial release.