CINXE.COM

<!DOCTYPE html><html lang="en" prefix="og: http://ogp.me/ns#" itemscope itemtype="http://schema.org/WebPage"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><title>Sample Gruntfile - Grunt: The JavaScript Task Runner</title><link rel="stylesheet" href="/css/main.css"><link rel="apple-touch-icon" href="/img/favicons/apple-touch-icon.png" sizes="180x180"><link rel="icon" type="image/png" href="/img/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/img/favicons/favicon-16x16.png" sizes="16x16"><link rel="manifest" href="/img/favicons/manifest.json"><link rel="mask-icon" href="/img/favicons/safari-pinned-tab.svg" color="#e48632"><link rel="shortcut icon" href="/img/favicons/favicon.ico" type="image/x-icon"><meta name="msapplication-config" content="/img/favicons/browserconfig.xml"><meta name="theme-color" content="#e48632"><meta property="og:title" content="Sample Gruntfile - Grunt: The JavaScript Task Runner"><meta property="og:type" content="website"><meta property="og:url" content="https://gruntjs.com/"><meta property="og:image" content="https://gruntjs.com/img/og.png"><meta property="og:image:type" content="image/png"><meta property="og:image:width" content="256"><meta property="og:image:height" content="256"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:creator" content="@gruntjs"><meta name="twitter:site" content="@gruntjs"><meta name="twitter:title" content="Sample Gruntfile - Grunt: The JavaScript Task Runner"><meta itemprop="name" content="Grunt"><meta itemprop="image" content="/img/og.png"><link href="/rss" rel="alternate" title="Grunt Blog Feed" type="application/atom+xml"></head><body class="page-docs page-secondary"><div class="banner"> <a href="support">V1.6.1 is the current version, and previous versions are not supported. Upgrade to the latest version or consider other support options.</a></div><div class="navbar navbar-inverse"><div class="navbar-inner"><div class="container"><a class="brand" href="/"></a><div class="nav-collapse collapse"><ul class="nav"><li><a href="/getting-started">Getting Started</a></li><li><a href="/configuring-tasks">Configuring Tasks</a></li><li><a href="/plugins">Plugins</a></li><li><a href="/documentation">Documentation</a></li><li><a href="/support">Support</a></li></ul><form class="navbar-search pull-right"><input class="search-query" type="text" placeholder="Search"></form></div></div></div></div><div class="content"><div class="container sample-gruntfile"><div class="row-fluid"><div class="span9 page"><div class="hero-unit"><h1>Sample Gruntfile</h1>In this page we walk you through the creation of a <code>Gruntfile</code> that covers the usual needs of a simple project. If you already know how to set up a <code>Gruntfile</code> and you're looking for a quick example, here's one: <pre><code class="lang-js">module.exports = function(grunt) { grunt.initConfig({ jshint: { files: ['Gruntfile.js', 'src/**/*.js', 'test/**/*.js'], options: { globals: { jQuery: true } } }, watch: { files: ['<%= jshint.files %>'], tasks: ['jshint'] } }); grunt.loadNpmTasks('grunt-contrib-jshint'); grunt.loadNpmTasks('grunt-contrib-watch'); grunt.registerTask('default', ['jshint']); };</code></pre> <h2><a class="anchor" href="#requirements" id="requirements"></a>Requirements</h2> Every project has its own needs, but most of them have something in common. In this guide we introduce you to a few Grunt plugins to automate basic requirements. The final goal is to teach you how to configure these Grunt plugins so that you can use them in your projects. For the sake of the example, let's say that you're creating a JavaScript library. The typical folder structure features the following folders: <code>src</code>, <code>dist</code>, and <code>test</code>. The <code>src</code> folder (sometimes called <code>app</code>) contains the source code of the library as you author it. The <code>dist</code> folder (sometimes called <code>build</code>) contains the distribution, a minified version of the source code. A minified file is one where all unnecessary characters, such as spaces, new lines, comments are removed, without affecting the functionality of the source code. Minified source code is especially useful for users of the project because it reduces the amount of data that needs to be transferred. Finally, the <code>test</code> folder contains the code to test the project. This set up will be used in the next sections when creating the <code>Gruntfile</code> configuration. While developing the library and releasing new versions there are a few tasks that you need to perform on a regular basis. For example, you might want to ensure that the code you write adheres to best practices, or that the code you've written doesn't result in unexpected behaviors. To do that, you can employ a tool called <a href="http://jshint.com/about/">JSHint</a>. Grunt has an official plugin for it called <a href="https://github.com/gruntjs/grunt-contrib-jshint">grunt-contrib-jshint</a> which we'll adopt in this example. In particular, you might want to ensure that as you modify your code, you don't break any rules or best practices. So, a good strategy is to check the code at every change you perform. To do that, we'll cover a Grunt plugin called <a href="https://github.com/gruntjs/grunt-contrib-watch">grunt-contrib-watch</a>. The latter runs predefined tasks, such as <code>grunt-contrib-jshint</code>, whenever files are added, changed, or deleted. Checking that your source code follows best practices is not enough to guarantee that it's stable and doesn't contain bugs. To create a robust project, you need to test it. There are several libraries you can adopt such as <a href="https://qunitjs.com/">QUnit</a> or <a href="http://jasmine.github.io/">Jasmine</a>. In this guide, we describe how to configure QUnit, and specifically <a href="https://github.com/gruntjs/grunt-contrib-qunit">grunt-contrib-qunit</a>, to test your code. When it comes to distributing your work, you want to offer a version as small in size as possible. To create a minified version you need a Grunt plugin like <a href="https://github.com/gruntjs/grunt-contrib-uglify">grunt-contrib-uglify</a>. Moreover, unless the project you're developing is very small, chances are that you've split the code in multiple files. While this is a good practice for the developer, you want users to include only one file. So, before minifying the code, you should concatenate the source files to create a single one. To achieve this goal you need a Grunt plugin like <a href="https://github.com/gruntjs/grunt-contrib-concat">grunt-contrib-concat</a>. To sum up, in this guide we'll use the following five Grunt plugins: <ul> <li><a href="https://github.com/gruntjs/grunt-contrib-uglify">grunt-contrib-uglify</a></li> <li><a href="https://github.com/gruntjs/grunt-contrib-qunit">grunt-contrib-qunit</a></li> <li><a href="https://github.com/gruntjs/grunt-contrib-concat">grunt-contrib-concat</a></li> <li><a href="https://github.com/gruntjs/grunt-contrib-jshint">grunt-contrib-jshint</a></li> <li><a href="https://github.com/gruntjs/grunt-contrib-watch">grunt-contrib-watch</a></li> </ul> If you're curious about what the final result looks like, the entire <code>Gruntfile</code> can be found at the bottom of this page. <h2><a class="anchor" href="#setting-up-the-gruntfile" id="setting-up-the-gruntfile"></a>Setting up the <code>Gruntfile</code></h2> The first part is the "wrapper" function, which encapsulates your Grunt configuration. <pre><code class="lang-js">module.exports = function(grunt) { };</code></pre> Within that function we can initialize our configuration object: <pre><code class="lang-js">grunt.initConfig({ });</code></pre> Next, we can store the project settings from the <code>package.json</code> file into the <code>pkg</code> property. This allows us to refer to the values of properties within our <code>package.json</code> file, as we'll see shortly. <pre><code class="lang-js">pkg: grunt.file.readJSON('package.json')</code></pre> This leaves us with this so far: <pre><code class="lang-js">module.exports = function(grunt) { grunt.initConfig({ pkg: grunt.file.readJSON('package.json') }); };</code></pre> Now we can define a configuration for each of the tasks we mentioned. The configuration object for a plugin lives as a property on the configuration object, that often shares the same name as its plugin. The configuration for <code>grunt-contrib-concat</code> goes in the configuration object under the <code>concat</code> key as shown below: <pre><code class="lang-js">concat: { options: { // define a string to put between each file in the concatenated output separator: ';' }, dist: { // the files to concatenate src: ['src/**/*.js'], // the location of the resulting JS file dest: 'dist/<%= pkg.name %>.js' } }</code></pre> Note how in the snippet above we refer to the <code>name</code> property that's in the JSON file. We access it by using <code>pkg.name</code> as earlier we defined the <code>pkg</code> property to be the result of loading the <code>package.json</code> file, which is then parsed to a JavaScript object. Grunt has a simple template engine to output the values of properties in the configuration object. Here we tell the <code>concat</code> task to concatenate all files that exist within <code>src/</code> and end in <code>.js</code>. Now let's configure the <code>grunt-contrib-uglify</code> plugin, which minifies the JavaScript code: <pre><code class="lang-js">uglify: { options: { // the banner is inserted at the top of the output banner: '/*! <%= pkg.name %> <%= grunt.template.today("dd-mm-yyyy") %> */\n' }, dist: { files: { 'dist/<%= pkg.name %>.min.js': ['<%= concat.dist.dest %>'] } } }</code></pre> This snippet tells <code>grunt-contrib-uglify</code> to create a file within <code>dist/</code> that contains the result of minifying the JavaScript files. Here we use <code><%= concat.dist.dest %></code> so uglify will minify the file that the concat task produces. Up to this point, we have configured the plugins to create the distribution version the library. It's now time to use <code>grunt-contrib-qunit</code> to automate the testing of the code. To do that, we need to give to specify the location of the test runner files, which are the HTML files QUnit runs on. The resulting code is reported below: <pre><code class="lang-js">qunit: { files: ['test/**/*.html'] },</code></pre> Once done, it's time to set up the configuration to ensure that the code of the project adheres to best practices. JSHint is a tool that can detect issues or potential issues like a high cyclomatic complexity, the use of the equality operator instead of the strict equality operator, and the definition of unused variables and functions. We advise you to analyze with <code>grunt-contrib-jshint</code> all the JavaScript files of your project, including <code>Gruntfile</code> and the test files. An example of configuration of <code>grunt-contrib-jshint</code> is the following: <pre><code class="lang-js">jshint: { // define the files to lint files: ['Gruntfile.js', 'src/**/*.js', 'test/**/*.js'], // configure JSHint (documented at http://www.jshint.com/docs/) options: { // more options here if you want to override JSHint defaults globals: { jQuery: true, console: true, module: true } } }</code></pre> This plugin takes an array of files and then an object of options. These are all <a href="http://www.jshint.com/docs/">documented on the JSHint site</a>. If you're happy with the plugin defaults, there's no need to redefine them in the Gruntfile. The last plugin left to configure is <code>grunt-contrib-watch</code>. We'll use it to run the <code>jshint</code> and the <code>qunit</code> tasks as soon as a JavaScript file is added, deleted, or modified. When it detects any of the files specified have changed (here, we use the same files we told JSHint to check), it will run the tasks you specify, in the order they appear. This can be run on the command line with <code>grunt watch</code>. Turning the previous description into a configuration for <code>grunt-contrib-watch</code> results in the snippet below: <pre><code class="lang-js">watch: { files: ['<%= jshint.files %>'], tasks: ['jshint', 'qunit'] }</code></pre> With this snippet, we've set up the configuration for all the plugins mentioned in the introduction. The last step to perform is to load in the Grunt plugins we need. All of these should have been previously installed through npm. <pre><code class="lang-js">grunt.loadNpmTasks('grunt-contrib-uglify'); grunt.loadNpmTasks('grunt-contrib-jshint'); grunt.loadNpmTasks('grunt-contrib-qunit'); grunt.loadNpmTasks('grunt-contrib-watch'); grunt.loadNpmTasks('grunt-contrib-concat');</code></pre> And finally set up some tasks. The most important of these tasks is the default task: <pre><code class="lang-js">// this would be run by typing "grunt test" on the command line grunt.registerTask('test', ['jshint', 'qunit']); // the default task can be run just by typing "grunt" on the command line grunt.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify']);</code></pre> The default task is executed when you invoke <code>Grunt</code> without specifying a task to execute (<code>grunt</code>). <h2><a class="anchor" href="#the-resulting-gruntfile" id="the-resulting-gruntfile"></a>The resulting <code>Gruntfile</code></h2> If you've followed this guide correctly you should have the following <code>Gruntfile</code>: <pre><code class="lang-js">module.exports = function(grunt) { grunt.initConfig({ pkg: grunt.file.readJSON('package.json'), concat: { options: { separator: ';' }, dist: { src: ['src/**/*.js'], dest: 'dist/<%= pkg.name %>.js' } }, uglify: { options: { banner: '/*! <%= pkg.name %> <%= grunt.template.today("dd-mm-yyyy") %> */\n' }, dist: { files: { 'dist/<%= pkg.name %>.min.js': ['<%= concat.dist.dest %>'] } } }, qunit: { files: ['test/**/*.html'] }, jshint: { files: ['Gruntfile.js', 'src/**/*.js', 'test/**/*.js'], options: { // options here to override JSHint defaults globals: { jQuery: true, console: true, module: true, document: true } } }, watch: { files: ['<%= jshint.files %>'], tasks: ['jshint', 'qunit'] } }); grunt.loadNpmTasks('grunt-contrib-uglify'); grunt.loadNpmTasks('grunt-contrib-jshint'); grunt.loadNpmTasks('grunt-contrib-qunit'); grunt.loadNpmTasks('grunt-contrib-watch'); grunt.loadNpmTasks('grunt-contrib-concat'); grunt.registerTask('test', ['jshint', 'qunit']); grunt.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify']); };</code></pre> <div class="end-link">Found an error in the documentation? <a href='https://github.com/gruntjs/grunt-docs/issues'>File an issue</a>.</div></div></div><div class="span3"><div class="well sidebar-nav"><ul class="nav nav-list"><li class="nav-header">Documentation</li><li><a href="/getting-started">Getting Started</a></li><li><a href="/configuring-tasks">Configuring Tasks</a></li><li><a class="active" href="/sample-gruntfile">Sample Gruntfile</a></li><li><a href="/creating-tasks">Creating Tasks</a></li><li><a href="/creating-plugins">Creating Plugins</a></li><li><a href="/using-the-cli">Using the CLI</a></li></ul><ul class="nav nav-list"><li class="nav-header">Advanced</li><li><a href="/api">API</a></li><li><a href="/installing-grunt">Installing Grunt</a></li><li><a href="/frequently-asked-questions">Frequently Asked Questions</a></li><li><a href="/project-scaffolding">Project Scaffolding</a></li></ul><ul class="nav nav-list"><li class="nav-header">Community</li><li><a href="/support">Support</a></li><li><a href="/help-resources">Help Resources</a></li><li><a href="/who-uses-grunt">Who uses Grunt</a></li><li><a href="/built-with-grunt-badge">Built with Grunt Badge</a></li><li><a href="/contributing">Contributing</a></li><li><a href="/development-team">Development Team</a></li></ul><ul class="nav nav-list"><li class="nav-header">Migration guides</li><li><a href="/upgrading-from-0.3-to-0.4">Upgrading from 0.3 to 0.4</a></li><li><a href="/upgrading-from-0.4-to-1.0">Upgrading from 0.4 to 1.0</a></li></ul></div></div></div></div></div><footer class="grunt-footer"><div class="inner"><div class="container"><ul class="pull-right"><li><a href="/blog">Blog</a></li><li><a href="/upgrading-from-0.3-to-0.4">Migration Guides</a></li><li><a href="/contributing">Contributing</a></li><li><a href="/development-team">Development Team</a></li><li class="social"><a href="https://github.com/gruntjs/" title="Grunt on GitHub"></a></li><li class="social"><a href="https://twitter.com/gruntjs/" title="Grunt on Twitter"></a></li><li class="social"><a href="/rss" title="Grunt blog RSS feed"></a></li><li class="openjs"><a href="https://openjsf.org/" title="OpenJS Foundation"><img src="/img/openjsf-color-textw.svg" alt="OpenJS Foundation" width="100" height="31"></a></li></ul></div></div></footer></body></html>