Ещё один пост о сборке front-end проекта

Убедитесь, что установлен npm.

npm -v

Установите необходимые глобальные модули (если ещё не установлены):

npm install -g gulp browserify babel jade stylus http-server

Сделайте форк репозитория.

git clone https://github.com/alexfedoseev/js-app-starter.git

Установите зависимости проекта (исполнять в корне репозитория):

npm install

Соберите проект в development окружении и запустите локальный сервер:

npm start

Откройте браузер и перейдите на lvh.me:3500

# устанавливаем переменную окружения
NODE_ENV=development

# запускаем локальный сервер на домене lvh.me и порте 3500
http-server -a lvh.me -p 3500

# запускаем gulp таски
gulp

# устанавливаем переменную окружения
NODE_ENV=production

# запускаем gulp-таск `build`
gulp build

Конфиг

/* file: lib/gulp/config.js */

html: {
  src: _src + _html,              // путь до jade-исходников
  dest: _public,                  // куда сохраняем собранное
  params: {                       // параметры для jade
    pretty: devBuild,             // убиваем отступы в html?
    locals: {                     // переменные, которые мы передаем в шаблоны
      pkgVersion: pkg.version     // сохраняем версию релиза в переменную `pkgVersion`
    }
  }
}

_Github

Таск

/* file: lib/gulp/tasks/html.js */

var gulp        = require('gulp'),
    jade        = require('gulp-jade'),
    jadeInherit = require('gulp-jade-inheritance'),
    gulpif      = require('gulp-if'),
    changed     = require('gulp-changed'),
    filter      = require('gulp-filter'),
    notifier    = require('../helpers/notifier'),
    config      = require('../config').html;

gulp.task('html', function(cb) {

  // берём все jade-файлы из директории src/html
  gulp.src(config.src + '*.jade')
      // если dev-сборка, то watcher пересобирает только изменённые файлы
      .pipe(gulpif(devBuild, changed(config.dest)))
      // корректно обрабатываем зависимости
      .pipe(jadeInherit({basedir: config.src}))
      // отфильтровываем не-партиалы (без `_` вначале)
      .pipe(filter(function(file) {
        return !//_/.test(file.path) || !/^_/.test(file.relative);
      }))
      // преобразуем jade в html
      .pipe(jade(config.params))
      // пишем html-файлы
      .pipe(gulp.dest(config.dest))
      // по окончании запускаем функцию
      .on('end', function() {
        notifier('html');  // уведомление (в консоли + всплывашка)
        cb();              // gulp-callback, сигнализирующий о завершении таска
      });

});

_Github

Структура папки src/html

| src
  |-- html
      |-- index.jade        # скелет страницы
      |-- components/       # компоненты страницы
          |-- _header.jade
      |-- helpers/          # переменные, миксины
          |-- _params.jade
          |-- _mixins.jade
      |-- meta/             # содержимое head, коды аналитики и пр.
          |-- _head.jade

_Github

Все партиалы снабжаем префиксом `_` (нижнее подчеркивание), чтобы при сборке мы могли их отфильтровать и игнорировать.

helpers/_variables.jade
Сохраняем необходимые параметры в переменные. Например, если у нас телефон стоит в нескольких местах страницы, то его лучше сохранить в переменную и в шаблонах использовать именно её.

/* file: src/html/helpers/_variables.jade */

- var release = pkgVersion          // переменная из gulp-конфига
- var phone = '8 800 CALL-ME-NOW'   // телефон

_Github

helpers/_mixins.jade
Часто используемые блоки можно обернуть в mixin.

/* file: src/html/helpers/_mixins.jade */

mixin phoneLink(phoneString)
  - var cleanPhone = phoneString.replace(/(|)|s|-/g, '')
  a(href="tel:#{cleanPhone}")= phoneString

// в верстке вставляем
// +phoneLink(phone)

_Github

index.jade
Скелет главной страницы.

/* file: src/html/index.jade */

include helpers/_variables    // импортируем переменные
include helpers/_mixins       // импортируем миксины

doctype html
html

  head
    include meta/_head

  body
    include components/_header
    include components/_some_component
    include components/_footer

_Github

meta/_head.jade
Содержимое head.

/* file: src/html/meta/_head.jade */

meta(charset="utf-8")

...

// Используем версию сборки, если нужно обновить js/css в кэше браузеров
link(rel="stylesheet" href="css/app.min.css?v=#{release}")
script(src="js/app.min.js?v=#{release}")

...

_Github

На проекте может возникнуть необходимость формировать несколько наборов js/css.

Например вы пишите фронт + админку. Или библиотеку в 2 вариантах: без зависимостей и в формате jQuery-плагина. Эти сборки нужно разделять. Для этого в настройках сборщика мы создаем массив:

/* file: lib/gulp/config.js */

/* Для библиотеки */
var bundles = [
  {
    name        : 'myLib', // название бандла
    global      : 'myLib', // это имя объекта, экспортируемого в глобальное пространство имён
    compress    : true,    // минифицируем? (неминифицированная версия сохранятся всегда)
    saveToDist  : true     // сохраняем в папку `/dist`?
  }
];


/* Для сайта / страницы приземления */
var bundles = [
  {
    name        : 'app', // название бандла
    global      : false, // ничем отсвечивать не надо
    compress    : true,  // минифицируем?
    saveToDist  : false  // сохраняем в папку `/dist`?
  },
    name        : 'admin',
    global      : false,
    compress    : true,
    saveToDist  : false
  }
];

_Github

js/css cборщики будут искать в папке с js/css исходниками соответствующий end-point файл (`app.js` или `app.styl`). Через этот end-point файл мы управляем всеми зависимостями бандла. Их структуру я покажу чуть ниже.

Перед передачей бандлов сборщику, мы предварительно пропускаем массив через хелпер `bundler`, который формирует объект с настройками.

Конфиг

/* file: lib/gulp/config.js */

scripts: {
  bundles: bundler(bundles, _js, _src, _dist, _public),       // пакуем бандлы
  banner: '/** ' + pkg.name + ' v' + pkg.version + ' **/n',  // задаем формат баннера для min.js
  extensions: ['.jsx'],                                       // указываем дополнительные расширения
  lint: {                                                     // параметры для jshint
    options: pkg.lintOptions,
    dir: _src + _js
  }
}

_Github

Таск

/* file: lib/gulp/tasks/scripts.js */

var gulp       = require('gulp'),
    browserify = require('browserify'),
    watchify   = require('watchify'),
    uglify     = require('gulp-uglify'),
    sourcemaps = require('gulp-sourcemaps'),
    derequire  = require('gulp-derequire'),
    source     = require('vinyl-source-stream'),
    buffer     = require('vinyl-buffer'),
    rename     = require('gulp-rename'),
    header     = require('gulp-header'),
    gulpif     = require('gulp-if'),
    notifier   = require('../helpers/notifier'),
    config     = require('../config').scripts;


gulp.task('scripts', function(cb) {

  // считаем кол-во бандлов
  var queue = config.bundles.length;

  // поскольку бандлов может быть несколько, оборачиваем сборщик в функцию, 
  // которая в качестве аргумента принимает bundle-объект с параметрами
  // позже запустим её в цикл
  var buildThis = function(bundle) {

    // отдаем bundle browserify
    var pack = browserify({
      // это для sourcemaps
      cache: {}, packageCache: {}, fullPaths: devBuild,
      // путь до end-point (app.js)
      entries: bundle.src,
      // если пишем модуль, то через этот параметр
      // browserify обернет всё в UMD-обертку
      // и при подключении объект будет доступен как bundle.global
      standalone: bundle.global,
      // дополнительные расширения
      extensions: config.extensions,
      // пишем sourcemaps?
      debug: devBuild
    });

    // сборка
    var build = function() {

      return (
          // browserify-сборка
          pack.bundle()
              // превращаем browserify-сборку в vinyl
              .pipe(source(bundle.destFile))
              // эта штука нужна, чтобы нормально работал `require` собранной библиотеки
              .pipe(derequire())
              // если dev-окружение, то сохрани неминифицированную версию в `public/` (зачем - не помню))
              .pipe(gulpif(devBuild, gulp.dest(bundle.destPublicDir)))
              // если сохраняем в папку `dist` - сохраняем
              .pipe(gulpif(bundle.saveToDist, gulp.dest(bundle.destDistDir)))
              // это для нормальной работы sourcemaps при минификации
              .pipe(gulpif(bundle.compress, buffer()))
              // если dev-окружение и нужна минификация — инициализируем sourcemaps
              .pipe(gulpif(bundle.compress && devBuild, sourcemaps.init({loadMaps: true})))
              // минифицируем
              .pipe(gulpif(bundle.compress, uglify()))
              // к минифицированной версии добавляем суффикс `.min`
              .pipe(gulpif(bundle.compress, rename({suffix: '.min'})))
              // если собираем для production - добавляем баннер с названием и версией релиза
              .pipe(gulpif(!devBuild, header(config.banner)))
              // пишем sourcemaps
              .pipe(gulpif(bundle.compress && devBuild, sourcemaps.write('./')))
              // сохраняем минифицированную версию в `/dist`
              .pipe(gulpif(bundle.saveToDist, gulp.dest(bundle.destDistDir)))
              // и в `public`
              .pipe(gulp.dest(bundle.destPublicDir))
              // в конце исполняем callback handleQueue (определен ниже)
              .on('end', handleQueue)
      );

    };

    // если нужны watchers
    if (global.isWatching) {
      // оборачиваем browserify-сборку в watchify
      pack = watchify(pack);
      // при обновлении файлов из сборки - пересобираем бандл
      pack.on('update', build);
    }

    // в конце сборки бандла
    var handleQueue = function() {
      // сообщаем, что всё собрали
      notifier(bundle.destFile);
      // если есть очередь
      if (queue) {
        // уменьшаем на 1
        queue--;
        // если бандлов больше нет, то сообщаем, что таск завершен 
        if (queue === 0) cb();
      }
    };

    return build();
  };

  // запускаем массив бандлов в цикл
  config.bundles.forEach(buildThis);

});

_Github

Структура папки src/js

| src/
  |-- js/
      |-- components/  # код компонентов
      |-- helpers/     # js-хелперы
      |-- app.js       # end-point бандла

_Github

app.js
Через этот файл мы рулим всеми зависимостями и порядком исполнения js-компонентов. Имя файла должно совпадать с именем бандла.

/* file: src/js/app.js */

/* Vendor */
import $ from 'jquery';

/* Components */
import myComponent from './components/my-component';


/* App */

$(document).ready(() => {

  myComponent();

});

_Github

В таких случаях используем browserify-shim: плагин, который позволяет превращать обычные библиотеки в CommonJS-совместимые модули. Итак, у нас есть jQuery-плагин `maskedinput`, которого нет в npm.

Добавляем в `package.json` преобразование и выставляем настройки для зависимости:

/* file: package.json */

"browserify": {
  "transform": [
    "babelify",
    "browserify-shim"  // добавляем преобразование
  ]
},

// у `browserify-shim` много вариантов подключения библиотек
// смотрите доки на github: https://github.com/thlorenz/browserify-shim
"browser": {
  "maskedinput": "./path/to/jquery.maskedinput.js"
},
"browserify-shim": {
  "maskedinput": {
    "exports": "maskedinput",
    "depends": [
      "jquery:jQuery"
    ]
  }
}

После этого мы можем подключать модуль:

require('maskedinput');

Конфиг

/* file: lib/gulp/config.js */

css: {
  bundles: bundler(bundles, _css, _src, _dist, _public), // пакуем бандлы
  src: _src + _css,                                      // указываем где лежать исходники для watcher
  params: {},                                            // если нужны настройки для stylus - указываем тут
  autoprefixer: {                                        // настраиваем autoprefixer
    browsers: ['> 1%', 'last 2 versions'],               // подо что ставим префиксы
    cascade: false                                       // красиво не надо, всё равно минифицируем
  },
  compress: {}                                           // если нужны настройки минификации - указываем тут
}

_Github

Таск

/* file: lib/gulp/tasks/css.js */

var gulp     = require('gulp'),
    process  = require('gulp-stylus'),
    prefix   = require('gulp-autoprefixer'),
    compress = require('gulp-minify-css'),
    gulpif   = require('gulp-if'),
    rename   = require('gulp-rename'),
    notifier = require('../helpers/notifier'),
    config   = require('../config').css;

/* Логика css-таска повторяет логику js-таска */

gulp.task('css', function(cb) {

  var queue = config.bundles.length;

  var buildThis = function(bundle) {

    var build = function() {
      return (
          gulp.src(bundle.src)
              .pipe(process(config.params))
              .pipe(prefix(config.autoprefixer))
              .pipe(gulpif(bundle.compress, compress(config.compress)))
              .pipe(gulpif(bundle.compress, rename({suffix: '.min'})))
              .pipe(gulp.dest(bundle.destPublicDir))
              .on('end', handleQueue)
      );
    };

    var handleQueue = function() {
      notifier(bundle.destFile);
      if (queue) {
        queue--;
        if (queue === 0) cb();
      }
    };

    return build();
  };

  config.bundles.forEach(buildThis);

});

_Github

Структура папки src/css

| src/
  |-- css/
      |-- components/            # стили компонентов
          |-- header.styl
          |-- footer.styl
      |-- globals/
          |-- fonts.styl         # подключаем фонты
          |-- global.styl        # глобальные настройки проекта
          |-- normalize.styl     # нормализуем / ресетим
          |-- variables.styl     # переменные
          |-- z-index.styl       # z-индексы проекта
      |-- helpers/
          |-- classes.styl       # вспомогательные классы
          |-- mixins.styl        # и миксины
      |-- sprite/
          |-- sprite.json        # json, генерируемый gulp.spritesmith
          |-- sprite.styl        # создаем из json css-классы
      |-- vendor/                # вендорные css складываем сюда
      |-- app.styl               # end-point бандла

_Github

app.styl
Через этот файл мы рулим порядком подключения css-компонентов. Имя файла должно совпадать с именем бандла.

/* file: src/css/app.styl */

@import "helpers/mixins"
@import "helpers/classes"
@import "globals/variables"
@import "globals/normalize"
@import "globals/z-index"
@import "globals/fonts"
@import "globals/global"
@import "sprite/sprite"
@import "vendor/*"
@import "components/*"

_Github