Пример Gruntfile

В этой странице мы покажем вам, как создать Gruntfile, который охватывает обычные потребности простого проекта. Если вы уже знаете, как настроить Gruntfile, и вам нужен быстрый пример, вот один:

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']);

};

Требования

Каждый проект имеет свои потребности, но большинство из них имеют нечто общее. В этом руководстве мы представим вам несколько плагинов Grunt для автоматизации основных требований. Конечная цель – научить вас, как настроить эти плагины Grunt, чтобы вы могли использовать их в своих проектах.

Для примера предположим, что вы создаете JavaScript-библиотеку. Типичная структура папок включает следующие папки: src, dist, и test. Папка src (иногда называемая app) содержит исходный код библиотеки по мере вашего написания. Папка dist (иногда называемая build) содержит дистрибутив, сжатую версию исходного кода. Сжатый файл – это файл, из которого удалены все ненужные символы, такие как пробелы, новые строки, комментарии, без нарушения функциональности исходного кода. Сжатый исходный код особенно полезен для пользователей проекта, потому что уменьшает количество передаваемых данных. Наконец, папка test содержит код для тестирования проекта. Эта структура будет использована в следующих разделах при создании конфигурации Gruntfile.

Во время разработки библиотеки и выпуска новых версий вам необходимо регулярно выполнять несколько задач. Например, вы можете убедиться, что написанный вами код соответствует лучшим практикам или что написанный вами код не приводит к неожиданному поведению. Для этого можно использовать инструмент под названием JSHint. Grunt имеет официальный плагин для него, называемый grunt-contrib-jshint, который мы применим в этом примере. В частности, вы можете убедиться, что при внесении изменений в код вы не нарушаете никаких правил или лучших практик. Поэтому хорошей стратегией является проверка кода при каждом внесенном изменении. Для этого мы рассмотрим плагин Grunt под названием grunt-contrib-watch. Последний выполняет предварительно определённые задачи, такие как grunt-contrib-jshint, всякий раз, когда файлы добавляются, изменяются или удаляются.

Проверка того, что ваш исходный код соответствует лучшим практикам, недостаточно для гарантии его стабильности и отсутствия ошибок. Для создания надёжного проекта необходимо его протестировать. Существует несколько библиотек, которые можно использовать, таких как QUnit или Jasmine. В этом руководстве мы описываем, как настроить QUnit, и в частности grunt-contrib-qunit, для тестирования вашего кода.

Что касается распространения вашей работы, вы хотите предложить версию с наименьшим размером. Для создания сжатой версии вам нужен плагин Grunt, например, grunt-contrib-uglify. Кроме того, если проект, над которым вы работаете, не очень небольшой, велика вероятность того, что вы разделили код на несколько файлов. Хотя это хорошая практика для разработчика, вы хотите, чтобы пользователи включали только один файл. Поэтому перед сжатием кода вы должны объединить исходные файлы, чтобы создать один файл. Для достижения этой цели вам нужен плагин Grunt, например, grunt-contrib-concat.

Подводя итог, в этом руководстве мы будем использовать следующие пять плагинов Grunt:

• grunt-contrib-uglify
• grunt-contrib-qunit
• grunt-contrib-concat
• grunt-contrib-jshint
• grunt-contrib-watch

Если вас интересует, как выглядит конечный результат, весь Gruntfile можно найти внизу этой страницы.

Настройка Gruntfile

Первая часть – это функция «обёртка», которая инкапсулирует вашу конфигурацию Grunt.

module.exports = function(grunt) {
};

Внутри этой функции мы можем инициализировать наш объект конфигурации:

grunt.initConfig({
});

Далее, мы можем сохранить настройки проекта из файла package.json в свойство pkg. Это позволяет нам ссылаться на значения свойств в нашем файле package.json, как мы увидим вскоре.

pkg: grunt.file.readJSON('package.json')

Это оставляет нам пока следующее:

module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json')
  });
};

Теперь мы можем определить конфигурацию для каждой из задач, о которых мы упоминали. Объект конфигурации для плагина хранится как свойство в объекте конфигурации, который часто имеет то же имя, что и плагин. Конфигурация для grunt-contrib-concat находится в объекте конфигурации под ключом concat, как показано ниже:

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'
  }
}

Обратите внимание, как в приведенном фрагменте мы ссылаемся на свойство name, которое находится в JSON-файле. Мы получаем доступ к нему, используя pkg.name, как ранее мы определили свойство pkg как результат загрузки файла package.json, который затем парсится в объект JavaScript. Grunt имеет простой движок шаблонов для вывода значений свойств в объекте конфигурации. Здесь мы говорим задаче concat объединить все файлы, которые существуют в src/ и заканчиваются на .js.

Теперь давайте настроим плагин grunt-contrib-uglify, который сжимает JavaScript-код:

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 %>']
    }
  }
}

Этот фрагмент говорит grunt-contrib-uglify создать файл в dist/, содержащий результат сжатия JavaScript-файлов. Здесь мы используем <%= concat.dist.dest %>, поэтому uglify будет сжимать файл, созданный задачей concat.

До этого момента мы настраивали плагины для создания дистрибутивной версии библиотеки. Теперь пришло время использовать grunt-contrib-qunit для автоматизации тестирования кода. Для этого нам нужно указать расположение файлов тестового исполнителя, которые являются HTML-файлами, на которых работает QUnit. Результирующий код представлен ниже:

qunit: {
  files: ['test/**/*.html']
},

После этого пришло время настроить конфигурацию, чтобы убедиться, что код проекта соответствует лучшим практикам. JSHint – это инструмент, который может обнаруживать проблемы или потенциальные проблемы, такие как высокая цикломатическая сложность, использование оператора равенства вместо строгого оператора равенства и определение неиспользуемых переменных и функций.

Мы рекомендуем вам проанализировать с помощью grunt-contrib-jshint все JavaScript-файлы вашего проекта, включая Gruntfile и файлы тестов. Пример конфигурации grunt-contrib-jshint следующий:

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
    }
  }
}

Этот плагин принимает массив файлов и затем объект опций. Все они документированы на сайте JSHint. Если вы удовлетворены значениями по умолчанию плагина, нет необходимости переопределять их в Gruntfile.

Последний плагин, который нужно настроить, это grunt-contrib-watch. Мы будем использовать его для запуска задач jshint и qunit всякий раз, когда добавляется, удаляется или изменяется JavaScript-файл. Когда он обнаруживает любые изменения указанных файлов (здесь мы используем те же файлы, которые мы сказали JSHint проверить), он выполнит указанные задачи в том порядке, в котором они появляются. Это можно выполнить из командной строки с помощью grunt watch.

Преобразование предыдущего описания в конфигурацию для grunt-contrib-watch приводит к фрагменту ниже:

watch: {
  files: ['<%= jshint.files %>'],
  tasks: ['jshint', 'qunit']
}

С этим фрагментом мы настроили конфигурацию для всех плагинов, упомянутых во введении. Последний шаг – загрузить необходимые нам плагины Grunt. Все они должны быть предварительно установлены через npm.

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');

И, наконец, настройте некоторые задачи. Самая важная из этих задач – задача по умолчанию:

// 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']);

Задача по умолчанию выполняется при вызове Grunt без указания задачи для выполнения (grunt).

Результирующий Gruntfile

Если вы правильно выполнили это руководство, у вас должна быть следующая Gruntfile:

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']);

};