Go back to the main page

Quickly test drive the creation of a Grunt plugin. Part 1.

 

 


Code from screencast and tutorial is available on Github. The screencast has more detail and explanation than this tutorial.

Have an idea that you would like to wrap into a Grunt plugin?

That was my exact situation as I wanted to be able to use the auto reloading behavior from the bootstrap-chrome-extension project in my Chrome extension work without manually copying and hooking up the reloading code for each new undertaking. After a good deal of trial and error I was able to publish the grunt-crx-auto-reload plugin. From that learning experience emerged this 3-part step-by-step tutorial series explaining how to create a Grunt plugin, TDD style.

AIM: Create a grunt plugin that will work in conjunction with grunt watch to automatically reload a Chrome extension.

  • Given that core Chrome extension code has been modified a timestamped reload.html should be created in the root of the extension directory.
  • Another file, reload.js must be created if it does not exist in the root extension directory.
    • The reload.js must be configured as a background script in the manifest.json.
    • The reload.js file must check reload.html every 1 second to see if the timestamp has changed. If the timestamp has changed then issue a chrome.runtime.reload() on reload.html.
  1. Start by using npm search gruntplugin [search term] for 2 purposes.
    1. To see if there already is a Grunt plugin that solves this problem.
    2. To help decide on a plugin name.
  2. After not finding another similar plugin, I settled on the plugin name grunt-crx-auto-reload.
  3. Create a working directory and install the Yeoman generator generator-gruntplugin.
    4. $ cd ~/github/labs
$ mkdir grunt-crx-auto-reload && cd $_
$ npm install -g generator-gruntplugin
  4. Run the generator-gruntplugin
    5. $ yo gruntplugin
    Answer the questions presented after running yo gruntplugin.
  5. The generator creates a scaffolding that includes all the required node modules, Gruntfile, tests, README, and a sample task.
    6. A sample task with the plugin name is created.
  6. The tests provided spec that sample task.
    7. The default test framework is Nodeunit
  7. The default task in the Gruntfile provided lints the code and runs the tests.
    8. Open the Gruntfile.js and explore what tasks have been setup.
    Run the tests by using the grunt command.
  8. Let's map a vim leader that will save the file and run the grunt command in the right tmux window pane.
    9. Now every time ,zl is typed the file is saved and tests run on the right window pane.
    The ts command is a bash function that shortens the tmux send-keys to right pane command. Here is the source: 
    function ts {
  args=$@
  tmux send-keys -t right "$args" C-m
}
    The first aim of this grunt plugin is to create a timestamped reload.html in the Chrome extension development directory. The Chrome extension directory will be supplied by the plugin user. The generator-gruntplugin uses the /tmp as a scratch directory for testing file creation. After each grunt run the /tmp directory is cleaned out.
  9. Open test/crx_auto_load_test.js, clean out the boilerplate code, and create your first test.
    10. Add a simple file existence test for the reload.html creation.
    I am using grunt.file.exists() is the above example. Coming up, grunt.template will also be leveraged. Check out the Grunt API for other helpful builtins.
  10. Comment out the test expectation for the custom_options test and run the test.
    11. The test.expect() will prevent you from achieving green if they are incorrect.
    Start with a failing test.
  11. Let's go back to the Gruntfile and see what is going on for these default_options and custom_options tests.
    12. These tasks have some predefined options and file operations.
    Keeping things simple, remove the options and file tasks.
  12. Edit tasks/crx_auto_load.js, remove the boilerplate code, and replace with the code in below figure.
    13. Another Grunt builtin, grunt.file.
  13. Save the file and run the tests.
    14. Bango! We're green.

Conclusion

This is a good place to take a breather. Although, I haven't done anything spectecular as of yet we have established a solid Grunt plugin foundation. Tutorials part 2 and 3 are coming but you can watch the screencasts now.

  • Pushed on 03/17/2014 by Christian