Автоматизация задач сборки 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
- masterpage
Где 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]
- masterpage
Режим с 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
Автор: Андрей Кольтяков