Issues

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.  

Note: For more information on creating these files yourself, check out the Sample Gruntfile page.

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.

Note: if you’re using Git, you’ll want to add these lines to your .gitignore file to exclude node artifacts from your repository.

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.

Note:  If you structure your source differently, you’ll want to use Grunt to copy the files (in the desired structure) to a temporary folder and point grunt-umbraco-package there.  For an example of this, check the Archetype Gruntfile, which compiles the code to the “/dist/” directory in the desired structure, and points the package task there.

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

Tom Fulton

Tom Fulton is co-founder of Tonic, a digital agency based out of Denver, Colorado—specializing in Umbraco based solutions. Tom has been actively involved in the Umbraco community for nearly a decade. In his spare time Tom enjoys writing packages, contributing to the Umbraco core, and explaining to anyone who will listen why the Umbraco CMS is made of unicorn dust.

comments powered by Disqus