node package manager


Release a new version of your Node-based project


Grunt plugin for automating all the release steps of your node lib or bower component, with optional publishing to npm.

Repetition Killed the Cat

Releasing a new version of your killer Node/Bower/Component/JS lib looks something like this:

  1. bump the version in your package.json file.
  2. stage the package.json file's change.
  3. commit that change with a message like "release 0.6.22".
  4. create a new git tag for the release.
  5. push the changes out to github.
  6. also push the new tag out to github.
  7. publish the new version to npm.

Cool, right? No! What's wrong with you? Automate all that:

grunt release

Done. No more github issues reminding you how often you forget to do one or more of the steps.


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

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


Using grunt-release

Patch Release:

grunt release


grunt release:patch

Minor Release:

grunt release:minor

Major Release:

grunt release:major


grunt release:prerelease

prerelease will just update the number after MAJOR.MINOR.PATCH (eg: 1.0.0-1) If you want to add an alphanumeric identifier, you will need to add it by hand. Example: add -alpha.0 to get something like 1.0.0-alpha.0. Calling grunt release:prerelease will just update the last number to 1.0.0-alpha.1.


grunt release:promote

promote will update a beta prerelease to stable. Example: for a version 1.0.0-beta, calling grunt release:promote will update the version to 1.0.0.

Releasing Stable Versions By default, grunt-vtex-release will append the "beta" prerelease tag to all versions. In order to release stable versions, you can:

  • Use the --tag stable option. e.g. grunt release:minor --tag stable
  • Use the shorcut: --stable. e.g. grunt release:minor --stable

Dry Run: To see what grunt-release does, without really changing anything, use --no-write option.

grunt --no-write -v release

You'll see something like:

Parsing package.json...OK
Not actually writing package.json...OK
>> Version bumped to 0.2.6
Not actually running: git add package.json
Not actually running: git commit package.json -m "release 0.2.6"
>> package.json committed
Not actually running: git tag 0.2.6 -m "version 0.2.6"
>> New git tag created: 0.2.6
Done, without errors.


The following are all the release steps, you can disable any you need to:

  release: {
    options: {
      bump: false, //default: true 
      file: 'component.json', //default: package.json 
      add: false, //default: true 
      commit: false, //default: true 
      tag: false, //default: true 
      push: false, //default: true 
      pushTags: false, //default: true 
      npm: false, //default: true 
      npmtag: true, //default: no tag 
      folder: 'folder/to/publish/to/npm' //default project root 
      tagName: 'some-tag-<%= version %>', //default: '<%= version %>' 
      commitMessage: 'check out my release <%= version %>', //default: 'release <%= version %>' 
      tagMessage: 'tagging version <%= version %>' //default: 'Version <%= version %>', 
      github: {
        repo: 'geddski/grunt-release', //put your user/repo here 
        usernameVar: 'GITHUB_USERNAME', //ENVIRONMENT VARIABLE that contains Github username 
        passwordVar: 'GITHUB_PASSWORD' //ENVIRONMENT VARIABLE that contains Github password 

Notes on Github Releases:

  1. Yes, you have to use environment variables. I would be a terrible person if I let you check in your username and password into your source code.
  2. The Github Releases API is still unstable and may change in the next couple months or so.
  3. You can use an access token if you'd rather.

For node libs, leave file option blank as it will default to package.json. For Bower components, set it to bower.json.