Grunt: Environment

Add environment-centric logic to your Grunt builds

Getting Started

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-environment --save-dev

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

grunt.initConfig({
  // ...

  environment: {
    default: 'development',
    environments: ['development', 'production'],
    version: function(){
      return grunt.file.readJSON('package.json')['version']
    },
    file: 'build.json'
  }

  // ...
});

grunt.loadNpmTasks('grunt-environment');

Any of the above options can also be a function except for the environments array.

The grunt-environment plugin will add the tasks environment:development and environment:production (for each entry in your environments array).

They will maintain state in a file called .grunt/environment.json in your project directory.

Divergent task configuration

There are two ways to create Grunt configuration for your environments.

Branched object

This bit of syntactic sugar added in v0.4.0 covers most common scenarios.

Example

config: {
  hostname: 'http://development.example.com', // (unaffected)
  development: {
    output_dir: 'build/development'
  },
  production: {
    output_dir: 'build/production'
  },
  environment: {
    default: 'development',
    environments: ['development', 'production']
  }
}

The environment you are using gets merged back into the main config:

grunt environment:production

...makes the config behave as if it were:

config: {
  hostname: 'http://development.example.com', // (unaffected)
  output_dir: 'build/production',
}

Conditional logic

For more complex configuration, you can also use grunt.config.get('environment.env') or it's handy alias grunt.environment() in your Grunt tasks to create conditions around these environments.

Example

// Environment-specific configuration for grunt-contrib-clean.
// When the **development** environment is active, `grunt clean` will remove files inside `build/development`
// When the **production** environment is active, `grunt clean` will remove files inside `build/production`

clean: {
  build: (function() {
    switch (grunt.environment()) {
      case 'development':
        return ['build/development'];
      case 'production':
        return ['build/production'];
    }
  })()
}

v0.2.0 adds the alias grunt.environment() to the current env value.

The additional keys timestamp and version are included as well.

You may find it useful to pass build as a variable into a template for your application to use at runtime.

Release History

0.4.2

• Extend to allow pulling environment vars from global config (see #4)

0.4.0

• Adds Branched Object merge feature suggested by @colwilson
• Adds dependency lodash (Grunt external libraries are deprecated)
• Original configuration is now preserved upon initialization as config.environment.meta

0.3.0

• No longer necessary to try/catch initialize manually after tasks are loaded
• Adds grunt environment (with no subtask) to echo current environment from file

0.2.1

• Small fixes

0.2.0

• Adds grunt.environment() alias
• Bit of overall refactoring
• Moves default storage from build.json to .grunt/environment.json
• Adds configurable options default, environments, version, file

0.1.0

• First release