Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/koltyakov/sp-build-tasks
👷 SharePoint front-end projects automation and tasks tool-belt
https://github.com/koltyakov/sp-build-tasks
automation build gulp javascript nodejs pnpjs react sharepoint tasks webpack
Last synced: about 2 months ago
JSON representation
👷 SharePoint front-end projects automation and tasks tool-belt
- Host: GitHub
- URL: https://github.com/koltyakov/sp-build-tasks
- Owner: koltyakov
- License: mit
- Created: 2017-05-19T14:15:39.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-03-29T16:55:46.000Z (10 months ago)
- Last Synced: 2024-04-14T09:51:40.679Z (9 months ago)
- Topics: automation, build, gulp, javascript, nodejs, pnpjs, react, sharepoint, tasks, webpack
- Language: TypeScript
- Homepage:
- Size: 3.57 MB
- Stars: 16
- Watchers: 4
- Forks: 6
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# sp-build-tasks
[](https://nodei.co/npm/sp-build-tasks/)
[](https://badge.fury.io/js/sp-build-tasks)
[](https://www.npmjs.com/package/sp-build-tasks)
[](https://gitter.im/sharepoint-node/Lobby)
> SharePoint front-end projects automation and tasks tool-belt
The library was designed for usage with [SharePoint Push-n-Pull](https://github.com/koltyakov/generator-sppp) Yeoman generator but can be used as a stand-alone package as well.
## Install
### Dependency
```bash
npm i sp-build-tasks --save-dev
```
### Integration to the code
```javascript
// gulpfile.js
const gulp = require('gulp');
require('dotenv').config();
new (require('sp-build-tasks').SPBuildTasks)(gulp, {
privateConf: process.env.PRIVATE_JSON || './config/private.json',
appConfig: process.env.APP_JSON || './config/app.json',
taskPath: './tools/tasks'
});
```
#### Settings
Parameter | Description
----------|------------
`privateConf` | path to [credentials](https://github.com/koltyakov/node-sp-auth-config) config file
`appConfig` | path to application config file
`taskPath` | path to custom gulp tasks folder
### App config file
The app config file should be a JSON document with the following schema `sp-build-tasks/schema/v1/sppp.json`.
The schema represents the following interface:
```javascript
export interface IAppConfig {
$schema?: string; // Path to `sp-build-tasks/schema/v1/sppp.json`
spFolder: string; // SharePoint relative target folder (e.i. `_catalogs/masterpage/contoso`)
distFolder: string; // Local distribution folder path
deleteFiles?: boolean; // Delete remote files on local files unlink event
masterpagePath?: string; // Path to masterpage .hbs in `./src` structure
masterpage?: any; // masterpage's custom properties passed to hbs template
masterpageCodeName?: string; // masterpage code name (used for renaming output file)
platformVersion?: string; // Masterpage platform version (2016, 2013, etc.)
logoPath?: string; // Path to logo image
bundleJSLibsFiles?: string[]; // Paths to .js files to bundle together in a single vendor.js
bundleCSSLibsFiles?: string[]; // Paths to .css files to bundle together in a single vendor.css
copyAssetsMap?: IAssetMap[]; // Custom static files copy configuration
customActions?: ICustomActionDefinition[];
customStyles?: IAssetMap | IAssetMap[]; // Custom styles
modulePath?: string; // Relative path for module inside dist structure, e.g. `modules/my-module`
customData?: any; // Optional custom data object that can be used for feeding data to templates
webpackItemsMap?: Array<{ entry: string; target: string; }>; // Scripts build configuration. Array or entry/target script pairs.
devtool?: Options.Devtool; // Webpack `devtool` option for development mode, i.e. `eval`
}
```
#### Custom Gulp tasks
```javascript
// `./build/tasks/example.js`
module.exports = (gulp, $, settings) => {
// gulp - Gulp object
// $ - Gulp plugins dynamic loader
// settings - ISPBuilderSettings object
gulp.task('example', cb => {
console.log('Example Gulp Task');
cb();
});
// ...
};
```
or types supported version:
```javascript
//@ts-check
const { customTask } = require('sp-build-tasks');
module.exports = customTask((gulp, $, settings) => {
gulp.task('example', cb => {
console.log('Example Gulp Task');
cb();
});
});
```
## Gulp tasks
### Authentication config setup initiation
```bash
gulp config
```
Populates `./config/private.json` with credentials options.
### Watch and live development
#### Watch
```bash
gulp watch
```
Watch for changes in `./src` folder, compiles .ts, .hbs and .scss to `./dist`.
Watch for changes in `./dist` and uploads to target SharePoint folder.
Use `--skipSync` flag to skip any upload to SharePoint assets, e.g. if you need external tools (like [gosip sync](https://github.com/koltyakov/gosip-sandbox/tree/master/samples/sync)) to be used instead of embeded.
#### Watch with SharePoint pages live reload
```bash
gulp live
```
Does the same as the `watch` task.
Emits files update to SharePoint live reload client which triggers live pages reload for:
- JavaScript's updates
- CSS's updates
- CEWPs updates
- Layouts updates
- Masterpage updates
### Syncronization
#### Publishing `./dist` to SharePoint
```bash
gulp push
```
Publishes all `./dist` folder content to SharePoint target folder.
#### Publishing in incremental mode
```bash
gulp push --diff
```
Uploads only files which size is different from those in SharePoint.
#### Fetching files from SharePoint
```bash
gulp pull
```
Downloads all files and folders from remote SharePoint target to `./dist` folder.
### Build front-end
```bash
gulp build
```
Compiles front-end to `./dist` folder.
#### Build options
##### Production build
```bash
gulp build --prod
```
Used with Webpack build.
##### Build subtasks
A specific subtasks can be provided as `gulp build` parameters:
Parameter | Description
----------|------------
--webpack | webpack'ing .ts to single app.js buldle
--css-custom | bundling custom css (from .scss)
--copy-assets | copying static content
--js-libs | bundling JavaScript libraries
--css-libs | bundling CSS libraries or custom .css
--masterpage | .hbs to .masterpage
--layouts | .hbs to .aspx layouts
--webparts | compiles .hbs CEWPs
```bash
gulp build --prod --webpack --webparts
```
Starts webparts and webpack tasks, also uses production build configs.
### Deployment
#### Live reload
```bash
gulp live-reload [--install]
```
Installs live reload client as ScriptLink custom action to SPWeb.
```bash
gulp live-reload --uninstall
```
Retracts live reload custom action client.
#### Masterpage
```bash
gulp masterpage [--install]
```
Applies custom masterpage and logo to SPWeb.
```bash
gulp masterpage --uninstall
```
Restores default (seattle.masterpage) masterpage.
#### Custom actions
```bash
gulp custom-actions [--install]
```
Provisions custom actions from `app.json` settings.
```bash
gulp custom-actions --uninstall
```
Removes custom actions based on project namespace prefix.