Автоматизация задач сборки front-end проектов SharePoint

Давно собирался описать и задокументировать основные задачи и настройки, входящие в состав проекта генератора SharePoint Push & Pull, предназначенного упростить процесс как генерации новых front-end проектов для классики SharePoint, так и предоставить набор действий по автоматизации от сборки до публикации. Как это часто бывает, документация не успевает за возможностями библиотеки, а некоторые моменты остаются неочевидны без просмотра исходников.

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

Довольно много разработчиков в комьюнити знает и используют generator-sppp, но не все знают, что основная функциональность достигается отдельной зависимостью, устанавливаемой в проект, - sp-build-tasks.

В данной статье я хочу пройтись по настройкам sp-build-tasks. Ниже представлено довольно много информации, она так же продублирована и актуализируется отдельно в рамках wiki в репозитории проекта.

sp-build-tasks

Библиотека разработана специально для использования в составе проектов, генерируемых с помощью SharePoint Push-n-Pull Yeoman генератора, но так же может быть и задействована отдельно.

Рекоммендуемое использование

Пререквизиты

  • Node.js (v.8 или выше)
  • NPM или Yarn
  • Yeoman
  • SPPP Yeoman генератор
  • TypeScript
  • Gulp CLI
npm install yarn yo generator-sppp typescript ts-lint gulp-cli -g

Создание нового проекта

Выполнить yo sppp в чистой папке нового проекта.

yo sppp

Опции сборки

С помощью опций сборки, в рамках конкретного проекта можно задать уникальный процесс, учитывающий нюансы проекта.

Настройки храняться в файле ./config/app.json.

Пример настроеку:

{
  "spFolder": "_catalogs/masterpage/spf",
  "distFolder": "./dist",

  "customStyles": [{
    "src": "styles/frankfurt/frankfurt.scss",
    "dist": "styles/frankfurt.min.css"
  }],

  "bundleJSLibsFiles": [
    "./node_modules/es6-promise/dist/es6-promise.auto.min.js",
    "./node_modules/whatwg-fetch/fetch.js",
    "./node_modules/sp-pnp-js/dist/pnp.js"
  ],

  "bundleCSSLibsFiles": [
    "./node_modules/datatables/media/css/jquery.dataTables.min.css"
  ],

  "copyAssetsMap": [{
    "src": [
      "./node_modules/datatables/media/images",
      "./src/images",
      "./src/scripts/modules/wysiwyg.js"
    ],
    "dist": "./dist"
  }],

  "webpackItemsMap": [{
    "entry": "./src/scripts/module-a.ts",
    "target": "module-a.js",
    "webpackConfig": {
      "cache": true,
      "devtool": "source-map",
      "plugins": []
    }
  }],
  "webpackConfig": {
    "cache": true,
    "devtool": "source-map",
    "plugins": []
  },

  "masterpagePath": "masterpage/frankfurt.master",
  "logoPath": "images/logo.png",
  "masterpageCodeName": "frankfurt",
  "platformVersion": "2016",
  "masterpage": {
    "copyright": {
      "year": "2017",
      "title": "Contoso intranet"
    }
  }
}

Опции сборки: Маппинг с каталогом SharePoint

Одна из локальных папок в проекте, по умолчанию это dist, проецируется и синхронизируется с папкой в библиотеке SharePoint. Так же, чаще всего эта папка является произвольной от других исходников и исключается из репозитория Git проекта. Я предпочитаю хранить активы приложений в _catalogs/masterpage/some_folder. Однако, это может быть любая библиотека, например: SiteAssets/some_folder или Style Library/some_folder.

Настройка взаимосвязи локальной и удаленной папки в SharePoint осуществляется в ./config/app.json в рамках следующих параметров:

{
  ...
  "spFolder": "_catalogs/masterpage/spf",
    // Относительный путь до папки в SPWeb, куда должны загружаться файлы проекта
  "distFolder": "./dist",
    // Локальная папка в проекте, куда производится бандлинг файлов проекта
  ...
}

Опции сборки: Webpack

В sp-build-tasks используется Webpack.

Возможно написание кода на TypeScript, ES (vNext) или чистом JavaScript без каких-либо дополнительных настроек.

Настройки Webpack задаются в ./webpack.config.js, сами настройки абсолютно стандартные для Webpack. В настройках задач сборки под Webpack есть раздел для сопоставления входных и результирующих файлов.

{
  ...
  // webpackItemsMap: массив или объект из входных и результирующих путей
  "webpackItemsMap": [{
    "entry": "./src/scripts/scriptName.ts",
      // Отновительный путь до .ts, .tsx, .js или .jsx
    "target": "scriptName.js",
      // Путь до результирующего файла относительно `./dist/stripts`
    "webpackConfig": {}
      // Опциональные настройки Webpack на случай необходимости уникальных
      // настроек для конкретной точки входа
  }],
  "webpackConfig": {},
    // Опциональные настройки Webpack
  ...
}

Опции сборки: Кастомные стили

В sp-build-tasks используется SCSS в качестве языка описания стилей. SCSS файлы так же могут хранить обычные CSS.

{
  ...
  // customStyles: массив или объект с источниками и назначением
  "customStyles": [{
    "src": "styles/frankfurt/frankfurt.scss",
      // Точка входа относительно папки './src'
    "dist": "styles/frankfurt.min.css"
      // Пуль до результирующего .css относительно './dist'
  }],
  ...
}

Опции сборки: JS библиотеки

В эпоху Webpack данная задача не сильно актуальна, но иногда может быть востребована и обоснована. Инструменты сборки могут бандлить сторонние библиотеки. Важно помнить, что при этом не производится транспиляции, поэтому исходные файлы должны быть совместимы с ES5 (или другой требуемой для браузера версии).

{
  ...
  "bundleJSLibsFiles": [
    "./node_modules/es6-promise/dist/es6-promise.auto.min.js",
    "./node_modules/whatwg-fetch/fetch.js",
    "./node_modules/sp-pnp-js/dist/pnp.js"
  ],
  ...
}

Рекомендуется установка сторонних библиотек через пакетные менеджеры.

Опции сборки: CSS библиотеки

Наряду с JS и Webpack и SCSS, а инструментах сборки есть возможность бандлить CSS.

{
  ...
  "bundleCSSLibsFiles": [
    "./node_modules/datatables/media/css/jquery.dataTables.min.css"
  ],
  ...
}

Рекомендуется установка сторонних библиотек через пакетные менеджеры.

Опции сборки: Копирование файлов

Рекомендованный подход предполагает хранение файлов, являющихся исходниками в папке ./src или других, входящих в состав отслеживаемых с помощью Git.

Файлы, которые можно охарактеризовать как внешние зависимости, не должны включаться в состав Git, но должны восстанавливаться пакетными менеджерами и включаться в итоговый бандл для загрузки в SharePoint. Даже в случае в Webpack, например, если библиотека отмечается как внешняя, ее нужно копировать.

На помощь приходит задача копирования файлов:

{
  ...
  // copyAssetsMap: массив или одиночный объект
  "copyAssetsMap": [{
    // src: массив или строка с путем до файла или папки
    "src": [
      "./node_modules/datatables/media/images",
      "./src/images",
      "./src/scripts/modules/wysiwyg.js"
    ],
    "dist": "./dist" // Папка назначения
  }],
  ...
}

Опции сборки: Брендинг

В составе sp-build-tasks фигурируют задачи по работе с брендингом, такие как сборка и публикация мастер страницы, лэйаутов или логотипа поратал.

{
  ...
  "masterpagePath": "masterpage/frankfurt.master",
    // Путь до файла с мастер страницей
    // Задействовано в задаче `gulp masterpage:apply`
  "logoPath": "images/logo.png",
    // Относительный путь до логотипа
    // Задействовано в задачах `gulp masterpage:apply` и `gulp logo:apply`
  "masterpageCodeName": "frankfurt",
    // Кодовое имя мастерстраницы
  "platformVersion": "2016",
    // Версия платформы (2016, 2013, пр.)
  "masterpage": {
    // Объект произвольной формы, значения которого могут подставляться в файлы .hbs при сборке
    "copyright": {
      "year": "2017",
      "title": "Contoso intranet"
    }
  }
  ...
}

Исходники мастерстраницы должны располагаться в стуркутуре:

  • src
    • masterpage
      • frankfurt.2016.hbs
      • frankfurt.2013.hbs

Где frankfurt является значением из masterpageCodeName, 2016 или 2013 определяются в platformVersion. .hbs - это шаблоны в формате handlebars, контент мастерстраницы (.aspx) изначально должен быть скопирован в .hbs.

Задачи

Перечень всех задач

gulp --tasks

Штатная команда получения всех зарегистрированных задач Gulp в рамках проекта.

Подключение к SharePoint
gulp config

Инициирует диалог подключения к SharePoint. Мастер подключения реализован с помощью node-sp-auth-config.

После завершения ввода параметров подключения, они сохраняются в ./config/private.json.

Посторный запуск задачи проверяет ./config/private.json и, если в параметрах не хватает требуемых, инициируется мастер.

Скачивание (pull)
gulp pull

Скачивает файлы из удаленной папки в SharePoint, заданной в spFolder. Данная задача может быть полезной в сценариях миграции, или же, если содержимое локального проекта не транспилируется.

Сборка front-end
gulp build

Команда запускает доступные задачи по сборке:

Бандлинг скриптов (typescript, javascript)
gulp build:webpack
Бандлинг стилей из SCSS
gulp build:css-custom
Копирование файлов
gulp build:copy-assets
Бандлинг внешних JS библиотек
gulp build:js-libs
Бандлинг внешних CSS библиотек
gulp build:css-libs
Сборка мастерстраницы
gulp build:masterpage
Сборка шаблонов страниц
gulp build:layouts
Сборка веб-частей (CEWP)
gulp build:webparts
Публикация (push)
gulp push

Загружает и публикует в SharePoint содержимое папки ./dist. Задача использует gulp-spsave для загрузки.

Отслеживание изменений
Стандартный режим
gulp watch

Мониторит изменения в локальных файлах и инициирует сборку и загрузку. Отслеживаются следующие папки и файлы:

  • src
    • masterpage
      • [файл мастерстраницы, .hbs]
      • layouts
        • [файлы шаблонов страниц, .hbs]
    • scripts
      • [изменения в .ts(x), .js(x)]
    • styles
      • [файлы стилей, .scss]
    • webparts
      • [вебчасти, .hbs]
Режим с hot-reload
gulp live

Мониторит файлы так же, как и gulp watch, но, при этом так же инициирует режим горячей перезагрузки страницы. Реализуется с помощью проактивного режима и сигнализации через веб-сокеты с помощью sp-live-reload.

Публикация
Применение мастер-страницы
gulp masterpage:apply

Применяет мастер-страницу на текущий сайт

Восстановление штатного Seattle
gulp masterpage:restore
Применение логотипа
gulp logo:apply
Установка горячей перезагрузки
gulp reload:install

Устанавливает ScriptLink хендлер мониторинга сокетов на сайт. Не рекомендуется для продакшен окружений.

Удаление горячей перезагрузки
gulp reload:retract

Удаляет ScriptLink хендлер мониторинга сокетов с сайта.

Прочие задачи
TypeScript

Транспиляция

gulp tsc

Транспилирует .ts файлы.

Линтинг

gulp tslint

Проверяет .ts по правилам TSLint.

Очистка временных файлов
gulp clean

Удяляет папки ./dist, ./tmp и ./cache.

Дополнительные задачи

В случае, когда требудется зарегистрировать свои задачи, инструменты сборки предоставляют возможность создания таковых в папке ./build/tasks. sp-build-tasks сканирует все JavaScript'ы в этой папке и, если они совпадают с форматом задачи, регистрирует для возможности исполнения.

Пример кастомной задачи:

//@ts-check

const { customTask } = require('sp-build-tasks');

module.exports = customTask((gulp, $, settings) => {

  gulp.task('example', cb => {
    console.log('Example Gulp Task');
    cb();
  });

});

Это не все возможности и особенности SPPP и sp-build-tasks, но основные, понимание которых должно позволить упростить рутинные задачи в части front-end для SharePoint.


Опубликовано: 24.09.2018
Автор: Андрей Кольтяков