Automating Umbraco Package Creation

So you’ve just built a snazzy new extension in Umbraco 7, have you? Excellent! Now, what is the best way to go about distributing it to the world?

Traditionally, one might use the Umbraco backoffice to create an Umbraco package, add the appropriate files, and “publish” it to a zip file. This works great, but requires a lot of manual steps each time you want to release a new version.

Wouldn’t it be great if you could automate this process?

Enter grunt-umbraco-package, a grunt task for automating the process of creating installable Umbraco packages from your code.

With a bit of configuration, this utility will allow you to generate an Umbraco package zip file by running a single command, through Grunt. You can also use CI to integrate this into your build or release processes.

Matt Brailsford first blogged about this technique in 2010, describing a similar method using MSBuild. Umbraco has come a long way since then, now allowing packages to be composed solely of JavaScript files, lending itself nicely for use with modern front-end build frameworks. You can still use MSBuild, or even Powershell, this post simply details another way to accomplish this using Grunt, as we happen to use that to manage other tasks when developing packages.

Show me!

Setup & Dependencies

This solution requires NodeJS and Grunt.  You might already be using Grunt to manage other tasks for your package, if so you can skip this step!  If not, you’ll need to install these dependencies on your system:

• NodeJS - download and install here

• Grunt - open a command prompt and run these commands to install grunt globally:

npm install -g grunt
npm install -g grunt-cli

You’ll also need to configure your codebase to work with NodeJS and Grunt.  To quickly get started, just download these sample files to the root of your repository: package.json, Gruntfile.js.  

Then, open a command prompt, switch to the root directory of your codebase and run this command to install node dependencies to your project:

npm install

This will create a “node_modules” folder in your repository and download the dependencies defined in the package.json file — currently just grunt and grunt-umbraco-package.

Configuration

To install grunt-umbraco-package, run:

npm install grunt-umbraco-package --save-dev

Next, add this line to your Gruntfile to load the task:

grunt.loadTask(‘grunt-umbraco-package’);

Then, add this block to your Gruntfile to define the task details:

umbracoPackage: {
  dist: {
    src: 'dist',
    dest: 'pkg',
	    options: {
	      name: ‘My Awesome Package’,
	      version: ‘<%= pkg.version %>’,
	      url: ‘http://github.com/johndoe/my-awesome-package’,
      	      license: ‘MIT’,
      licenseUrl: ‘http://opensource.org/licenses/MIT’,
      author: ‘John Doe’,
      authorUrl: ‘http://our.umbraco.org/member/1234’
	    }
  }
}

Let’s take a look at this configuration.  The defaults assume that your package files live in the “/src/” directory, and are in the desired structure to be installed into an Umbraco site.  The package will be created in the `/pkg` directory.  In the options object, add the details for your package — these will be used to generate Umbraco’s package.xml file.

We also pull the version number from the package.json and inject it using grunt templates, which you can use to manage this or other settings externally.

Run

Now that we’re all setup, just run grunt umbracoPackage to create your package.  Once completed, you should see the file in /pkg/MyAwesomePackage_0.1.zip

When it’s time to release a new version, simply bump the version number in your package.json, and run grunt umbraco again.

Conclusion

Now that your package is built, upload it to our.umbraco.org to share with the world!  You might also wish to make your package available via NuGet, see the further reading section for tips on this.

Hopefully this saves you some while building Umbraco packages in the future!

Further Reading

• Umbraco Packaging with AppVeyor CI - alternate method for automating package creation using MSBuild, and how to integrate this with your CI process

• Powershell script to create an Umbraco package - another alternate method detailed by Shannon Deminick, using Powershell

• Creating a NuGet Package - article by Kevin Giszewski detailing a similar technique for creating a NuGet version of your package

• Automating Umbraco Package Creation with MSBuild - a 2010 post from Matt Brailsford explaining the same process using MSBuild.  This post inspired grunt-umbraco-package!