Grunt

Плагины Grunt и Grunt устанавливаются и управляются через npm, менеджер пакетов Node.js. Grunt 0.4.x требует стабильных версий Node.js >= 0.8.0.

Перед настройкой Grunt убедитесь, что ваш npm обновлён, выполнив npm update -g npm (на некоторых системах это может потребовать sudo).

Если Grunt уже установлен и вам нужна быстрая справка, ознакомьтесь с нашим Gruntfile примером и как настроить задачу.

Установка CLI

Используете Grunt 0.3? Пожалуйста, см. Примечания по Grunt 0.3

Для начала вам нужно установить командную строку интерфейса (CLI) Grunt глобально. Возможно, вам потребуется использовать sudo (для OSX, *nix, BSD и т. д.) или запустить командную оболочку с правами администратора (для Windows).

npm install -g grunt-cli

Это добавит команду grunt в вашу системную переменную PATH, что позволит её запускать из любой директории.

Обратите внимание, что установка grunt-cli не устанавливает движок задач Grunt! Задача CLI Grunt проста: запустить установленную версию Grunt, которая находится рядом с Gruntfile. Это позволяет устанавливать на одном компьютере несколько версий Grunt одновременно.

Как работает CLI

Каждый раз, когда запускается grunt , ищет локально установленный Grunt с использованием системы require() Node.js. Благодаря этому, вы можете запускать grunt из любой подпапки вашего проекта.

Если локально установлен Grunt, CLI загружает локальную установку библиотеки Grunt, применяет конфигурацию из вашего Gruntfile и выполняет запрошенные вами задачи. Чтобы по-настоящему понять, что происходит, прочитайте код.

Работа с существующим проектом Grunt

Предполагая, что CLI Grunt установлен, и проект уже настроен с package.json и Gruntfile, работать с Grunt очень легко:

Перейдите в корневую директорию проекта.
Установите зависимости проекта с помощью npm install.
Запустите Grunt с помощью grunt.

Это все, что нужно. Установленные задачи Grunt можно перечислить, запустив grunt --help, но обычно лучше начать с документации проекта.

Подготовка нового проекта Grunt

Типичная настройка включает добавление двух файлов в ваш проект: package.json и Gruntfile.

package.json: Этот файл используется npm для хранения метаданных проектов, опубликованных как модули npm. Вы перечислите grunt и плагины Grunt, необходимые для вашего проекта, как devDependencies в этом файле.

Gruntfile: Этот файл называется Gruntfile.js или Gruntfile.coffee и используется для настройки или определения задач и загрузки плагинов Grunt. Когда в этой документации упоминается Gruntfile , это относится к файлу, который является либо Gruntfile.js, либо Gruntfile.coffee.

package.json

Файл package.json должен находиться в корневой директории вашего проекта, рядом с Gruntfile, и должен быть добавлен в вашу систему контроля версий.

Запуск npm install в той же папке, что и файл package.json, установит правильную версию каждой зависимости, указанной в нём.

Существует несколько способов создания файла package.json для вашего проекта:

Большинство шаблонов grunt-init автоматически создадут проект-специфичный файл package.json.
Команда npm init создаст базовый файл package.json.
Начните с примера ниже и расширяйте его по мере необходимости, следуя этой спецификации.

{
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.5",
    "grunt-contrib-jshint": "~0.10.0",
    "grunt-contrib-nodeunit": "~0.4.1",
    "grunt-contrib-uglify": "~0.5.0"
  }
}

Установка Grunt и gruntplugins

Самый простой способ добавить Grunt и gruntplugins к существующему package.json — это команда npm install <module> --save-dev. Это не только установит <module> локально, но и автоматически добавит его в раздел devDependencies, используя диапазон версий с тильдой.

Например, это установит последнюю версию Grunt в вашей папке проекта, добавив её в devDependencies:

npm install grunt --save-dev

То же самое можно сделать для gruntplugins и других модулей node. Как показано в следующем примере установки модуля задачи JSHint:

npm install grunt-contrib-jshint --save-dev

Просмотрите доступные в настоящее время gruntplugins для установки и использования в вашем проекте на странице плагинов.

Не забудьте добавить обновлённый файл package.json в систему контроля версий, когда закончите!

Файл Gruntfile

Файл Gruntfile.js или Gruntfile.coffee — это допустимый JavaScript или CoffeeScript файл, который должен находиться в корневой директории вашего проекта, рядом с файлом package.json, и должен быть добавлен в систему контроля версий.

Файл Gruntfile состоит из следующих частей:

Функция "оболочки"
Настройка проекта и задач
Загрузка плагинов и задач Grunt
Пользовательские задачи

Пример Gruntfile

В следующем Gruntfile, метаданные проекта импортируются в конфигурацию Grunt из файла package.json проекта, а задача uglify плагина grunt-contrib-uglify настраивается на минимизацию исходного файла и динамическое создание комментария баннера с использованием этих метаданных. При запуске grunt в командной строке, задача uglify будет выполнена по умолчанию.

module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
      },
      build: {
        src: 'src/<%= pkg.name %>.js',
        dest: 'build/<%= pkg.name %>.min.js'
      }
    }
  });

  // Load the plugin that provides the "uglify" task.
  grunt.loadNpmTasks('grunt-contrib-uglify');

  // Default task(s).
  grunt.registerTask('default', ['uglify']);

};

Теперь, когда вы увидели весь Gruntfile, давайте рассмотрим его составные части.

Функция "оболочки"

Каждый файл Gruntfile (и gruntplugin) использует этот базовый формат, и весь ваш код Grunt должен быть указан внутри этой функции:

module.exports = function(grunt) {
  // Do grunt-related things in here
};

Настройка проекта и задач

Большинство задач Grunt полагаются на данные конфигурации, определённые в объекте, переданном методу grunt.initConfig.

В этом примере, grunt.file.readJSON('package.json') импортирует JSON метаданные, хранящиеся в package.json, в конфигурацию grunt. Поскольку <% %> шаблоны строк могут ссылаться на любые свойства конфигурации, данные конфигурации, такие как пути к файлам и списки файлов, могут быть указаны таким образом, чтобы сократить повторение.

Вы можете хранить любые произвольные данные внутри объекта конфигурации, и, пока они не конфликтуют со свойствами, необходимыми вашим задачам, они будут игнорироваться. Кроме того, поскольку это JavaScript, вы не ограничены JSON; вы можете использовать здесь любой допустимый JS. Вы даже можете программно генерировать конфигурацию, если необходимо.

Как и большинство задач, задача uglify плагина grunt-contrib-uglify ожидает, что её конфигурация будет указана в свойстве с тем же именем. Здесь указан параметр banner, а также одна цель минимизации build, которая минимизирует один исходный файл в один файл назначения.

// Project configuration.
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  uglify: {
    options: {
      banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
    },
    build: {
      src: 'src/<%= pkg.name %>.js',
      dest: 'build/<%= pkg.name %>.min.js'
    }
  }
});

Загрузка плагинов и задач Grunt

Многие часто используемые задачи, такие как конкатенация, минификация и проверка кода, доступны как плагины grunt. Пока плагин указан в package.json в качестве зависимости и был установлен через npm install, он может быть включён в вашем Gruntfile простой командой:

// Load the plugin that provides the "uglify" task.
grunt.loadNpmTasks('grunt-contrib-uglify');

Примечание: команда grunt --help выведет список всех доступных задач.

Пользовательские задачи

Вы можете настроить Grunt на выполнение одной или нескольких задач по умолчанию, определив задачу default. В следующем примере, запуск grunt в командной строке без указания задачи, запустит задачу uglify. Это функционально эквивалентно явным запускам grunt uglify или даже grunt default. В массиве может быть указано любое количество задач (с аргументами или без).

// Default task(s).
grunt.registerTask('default', ['uglify']);

Если ваш проект требует задач, не предоставленных плагином Grunt, вы можете определить пользовательские задачи прямо в Gruntfile. Например, этот Gruntfile определяет полностью пользовательскую задачу default , которая даже не использует конфигурацию задач:

module.exports = function(grunt) {

  // A very basic default task.
  grunt.registerTask('default', 'Log some stuff.', function() {
    grunt.log.write('Logging some stuff...').ok();
  });

};

Пользовательские задачи, специфичные для проекта, не обязательно должны быть определены в файле Gruntfile; они могут быть определены во внешних .js файлах и загружены с помощью метода grunt.loadTasks.

Дополнительное чтение

В руководстве Установка grunt содержится подробная информация об установке определённых, производственных или находящихся в разработке, версий Grunt и grunt-cli.
В руководстве Настройка задач подробно объясняется, как настраивать задачи, цели, параметры и файлы внутри Gruntfile, а также объяснение шаблонов, шаблонов подстановки и импорта внешних данных.
В руководстве Создание задач указаны различия между типами задач Grunt и показаны примеры задач и конфигураций.
Для получения дополнительной информации о написании пользовательских задач или плагинов Grunt, ознакомьтесь с документацией разработчика.