{"id":21655957,"url":"https://github.com/koltyakov/sp-build-tasks","last_synced_at":"2025-04-11T21:32:56.915Z","repository":{"id":21210031,"uuid":"91813072","full_name":"koltyakov/sp-build-tasks","owner":"koltyakov","description":"👷 SharePoint front-end projects automation and tasks tool-belt","archived":false,"fork":false,"pushed_at":"2024-03-29T16:55:46.000Z","size":3740,"stargazers_count":16,"open_issues_count":12,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-14T09:51:40.679Z","etag":null,"topics":["automation","build","gulp","javascript","nodejs","pnpjs","react","sharepoint","tasks","webpack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koltyakov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-19T14:15:39.000Z","updated_at":"2024-05-14T01:36:33.504Z","dependencies_parsed_at":"2024-05-14T01:48:40.914Z","dependency_job_id":null,"html_url":"https://github.com/koltyakov/sp-build-tasks","commit_stats":{"total_commits":383,"total_committers":8,"mean_commits":47.875,"dds":0.5300261096605744,"last_synced_commit":"d5643d8f6d19e8eb98538022173f53799ee339d1"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-build-tasks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-build-tasks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-build-tasks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-build-tasks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koltyakov","download_url":"https://codeload.github.com/koltyakov/sp-build-tasks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482880,"owners_count":21111397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","build","gulp","javascript","nodejs","pnpjs","react","sharepoint","tasks","webpack"],"created_at":"2024-11-25T08:37:55.357Z","updated_at":"2025-04-11T21:32:56.891Z","avatar_url":"https://github.com/koltyakov.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sp-build-tasks\n\n[![NPM](https://nodei.co/npm/sp-build-tasks.png?mini=true\u0026downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/sp-build-tasks/)\n\n[![npm version](https://badge.fury.io/js/sp-build-tasks.svg)](https://badge.fury.io/js/sp-build-tasks)\n[![Downloads](https://img.shields.io/npm/dm/sp-build-tasks.svg)](https://www.npmjs.com/package/sp-build-tasks)\n![Build Status](https://koltyakov.visualstudio.com/SPNode/_apis/build/status/sp-build-tasks?branchName=master)\n[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/sharepoint-node/Lobby)\n\n\u003e SharePoint front-end projects automation and tasks tool-belt\n\n![banner](https://raw.githubusercontent.com/koltyakov/sp-build-tasks/master/docs/sp-build-tasks.png)\n\nThe 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.\n\n## Install\n\n### Dependency\n\n```bash\nnpm i sp-build-tasks --save-dev\n```\n\n### Integration to the code\n\n```javascript\n// gulpfile.js\n\nconst gulp = require('gulp');\nrequire('dotenv').config();\n\nnew (require('sp-build-tasks').SPBuildTasks)(gulp, {\n  privateConf: process.env.PRIVATE_JSON || './config/private.json',\n  appConfig: process.env.APP_JSON || './config/app.json',\n  taskPath: './tools/tasks'\n});\n```\n\n#### Settings\n\nParameter | Description\n----------|------------\n`privateConf` | path to [credentials](https://github.com/koltyakov/node-sp-auth-config) config file\n`appConfig` | path to application config file\n`taskPath` | path to custom gulp tasks folder\n\n### App config file\n\nThe app config file should be a JSON document with the following schema `sp-build-tasks/schema/v1/sppp.json`.\n\nThe schema represents the following interface:\n\n```javascript\nexport interface IAppConfig {\n  $schema?: string; // Path to `sp-build-tasks/schema/v1/sppp.json`\n  spFolder: string; // SharePoint relative target folder (e.i. `_catalogs/masterpage/contoso`)\n  distFolder: string; // Local distribution folder path\n  deleteFiles?: boolean; // Delete remote files on local files unlink event\n  masterpagePath?: string; // Path to masterpage .hbs in `./src` structure\n  masterpage?: any; // masterpage's custom properties passed to hbs template\n  masterpageCodeName?: string; // masterpage code name (used for renaming output file)\n  platformVersion?: string; // Masterpage platform version (2016, 2013, etc.)\n  logoPath?: string; // Path to logo image\n  bundleJSLibsFiles?: string[]; // Paths to .js files to bundle together in a single vendor.js\n  bundleCSSLibsFiles?: string[]; // Paths to .css files to bundle together in a single vendor.css\n  copyAssetsMap?: IAssetMap[]; // Custom static files copy configuration\n  customActions?: ICustomActionDefinition[];\n  customStyles?: IAssetMap | IAssetMap[]; // Custom styles\n  modulePath?: string; // Relative path for module inside dist structure, e.g. `modules/my-module`\n  customData?: any; // Optional custom data object that can be used for feeding data to templates\n  webpackItemsMap?: Array\u003c{ entry: string; target: string; }\u003e; // Scripts build configuration. Array or entry/target script pairs.\n  devtool?: Options.Devtool; // Webpack `devtool` option for development mode, i.e. `eval`\n}\n```\n\n#### Custom Gulp tasks\n\n```javascript\n// `./build/tasks/example.js`\nmodule.exports = (gulp, $, settings) =\u003e {\n\n  // gulp - Gulp object\n  // $ - Gulp plugins dynamic loader\n  // settings - ISPBuilderSettings object\n\n  gulp.task('example', cb =\u003e {\n    console.log('Example Gulp Task');\n    cb();\n  });\n\n  // ...\n};\n```\n\nor types supported version:\n\n```javascript\n//@ts-check\n\nconst { customTask } = require('sp-build-tasks');\n\nmodule.exports = customTask((gulp, $, settings) =\u003e {\n\n  gulp.task('example', cb =\u003e {\n    console.log('Example Gulp Task');\n    cb();\n  });\n\n});\n```\n\n## Gulp tasks\n\n### Authentication config setup initiation\n\n```bash\ngulp config\n```\n\nPopulates `./config/private.json` with credentials options.\n\n### Watch and live development\n\n#### Watch\n\n```bash\ngulp watch\n```\n\nWatch for changes in `./src` folder, compiles .ts, .hbs and .scss to `./dist`.\nWatch for changes in `./dist` and uploads to target SharePoint folder.\n\nUse `--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.\n\n#### Watch with SharePoint pages live reload\n\n```bash\ngulp live\n```\n\nDoes the same as the `watch` task.\nEmits files update to SharePoint live reload client which triggers live pages reload for:\n\n- JavaScript's updates\n- CSS's updates\n- CEWPs updates\n- Layouts updates\n- Masterpage updates\n\n### Syncronization\n\n#### Publishing `./dist` to SharePoint\n\n```bash\ngulp push\n```\n\nPublishes all `./dist` folder content to SharePoint target folder.\n\n#### Publishing in incremental mode\n\n```bash\ngulp push --diff\n```\n\nUploads only files which size is different from those in SharePoint.\n\n#### Fetching files from SharePoint\n\n```bash\ngulp pull\n```\n\nDownloads all files and folders from remote SharePoint target to `./dist` folder.\n\n### Build front-end\n\n```bash\ngulp build\n```\n\nCompiles front-end to `./dist` folder.\n\n#### Build options\n\n##### Production build\n\n```bash\ngulp build --prod\n```\n\nUsed with Webpack build.\n\n##### Build subtasks\n\nA specific subtasks can be provided as `gulp build` parameters:\n\nParameter | Description\n----------|------------\n--webpack | webpack'ing .ts to single app.js buldle\n--css-custom | bundling custom css (from .scss)\n--copy-assets | copying static content\n--js-libs | bundling JavaScript libraries\n--css-libs | bundling CSS libraries or custom .css\n--masterpage | .hbs to .masterpage\n--layouts | .hbs to .aspx layouts\n--webparts | compiles .hbs CEWPs\n\n```bash\ngulp build --prod --webpack --webparts\n```\n\nStarts webparts and webpack tasks, also uses production build configs.\n\n### Deployment\n\n#### Live reload\n\n```bash\ngulp live-reload [--install]\n```\n\nInstalls live reload client as ScriptLink custom action to SPWeb.\n\n```bash\ngulp live-reload --uninstall\n```\n\nRetracts live reload custom action client.\n\n#### Masterpage\n\n```bash\ngulp masterpage [--install]\n```\n\nApplies custom masterpage and logo to SPWeb.\n\n```bash\ngulp masterpage --uninstall\n```\n\nRestores default (seattle.masterpage) masterpage.\n\n#### Custom actions\n\n```bash\ngulp custom-actions [--install]\n```\n\nProvisions custom actions from `app.json` settings.\n\n```bash\ngulp custom-actions --uninstall\n```\n\nRemoves custom actions based on project namespace prefix.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fsp-build-tasks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoltyakov%2Fsp-build-tasks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fsp-build-tasks/lists"}