gulp-spsync-creds

Gulp plugin for synchronizing local files with a SharePoint library

This Gulp plugin is based on gulp-spsync which has been created by Wictor Wilen. The difference with gulp-spsync is that this plugin makes use for client credentials (username and password) in order to upload and/or download files. This makes the plugin usable for both SharePoint Online and on-premises environments.

Installation

Run the following command to install the gulp-spsync-creds plugin:

$ npm install gulp-spsync-creds

Usage

Uploading files

For uploading files, you can add the following code to your gulpfile.js:

var gulp = require('gulp');
var spsync = require('gulp-spsync-creds').sync;
 
gulp.src('./src/**/*')
.pipe(spsync({
    "username": "<username>",
    "password": "<password>",
    "site": "<site-url>",
}));

Downloading files

For downloading files, you can add the following code to your gulpfile.js:

var gulp = require('gulp');
var spdwn = require('gulp-spsync-creds').download;
 
spdwn({
    "site": "<site-url>",
    "username": "<username>",
    "password": "<password>",
    "startFolder": "<relative-folder-location>"
}).pipe(gulp.dest("src"));

Information: it currently retrieves all files of the given path and the ones of three folders deep.

Options

The plugin has the following options that can be configured:

username

Type: String Default: null

Sets the username to be used for the sync action.

password

Type: String Default: null

Sets the password to be used for the sync action.

site

Type: String Default: ""

Sets the site URL to where the files should be uploaded.

startFolder

Type: String Default: ""

Choose the name of the folder location it has to starts from. This is useful when you have a nested folder structure. Example: if your folder structure is like this src/template1/_sp/_catalogs, and you set the startFolder option to _sp, it will strip out all the folder names before including _sp. You end up with _catalogs.

Important: this property can also be used to specify the location from where you want to download files.

libraryPath New property - v2.3.0

Type: string Default: ""

The libraryPath property can be used if you want to define a default library path to where you want to upload your files.

By default the plugin uploads the files based on their file location (under your source folder).

src
|_ _catalogs
   |_ masterpage
      |_ your-folder
         |_ file1.html

So in the above case, file1.html will be uploaded to the master page gallery (_catalogs/masterpage) in a your-folder folder.

When you define the libaryPath to for example: documents. The plugin will upload the files to that specific document library with the folder structure. So in this case it will be documents/_catalogs/masterpage/your-folder/file1.html.

update_metadata

Type: Boolean Default: false

Specify if you want to update the metadata of files you are uploading. If this is set to true, you will have to pass the file metadata via the files_metadata option.

files_metadata

Type: Object Default: []

With the files_metadata option you can specify the metadata of all the files you wish to upload. Example:

"fileMetadata": [
    {
        "name": "Item_Minimal.js",
        "metadata": {
            "__metadata": {
                "type": "SP.Data.OData__x005f_catalogs_x002f_masterpageItem"
            },
            "Title": "Item Minimal Template (via GULP)",
            "MasterPageDescription": "This is a display template added via gulp.",
            "ManagedPropertyMapping": "'Path','Title':'Title'",
            "ContentTypeId": "0x0101002039C03B61C64EC4A04F5361F38510660500A0383064C59087438E649B7323C95AF6",
            "DisplayTemplateLevel": "Item",
            "TemplateHidden": false,
            "TargetControlType": {
                "__metadata": {
                "type": "Collection(Edm.String)"
                },
                "results": [
                "SearchResults",
                "Content Web Parts"
                ]
            }
        }
    },
    {
        "name": "Control_Minimal.js",
            "metadata": {
            "__metadata": {
                "type": "SP.Data.OData__x005f_catalogs_x002f_masterpageItem"
            },
            "Title": "Control Minimal Template (via GULP)",
            "MasterPageDescription": "This is a display template added via gulp.",
            "ContentTypeId": "0x0101002039C03B61C64EC4A04F5361F38510660500A0383064C59087438E649B7323C95AF6",
            "DisplayTemplateLevel": "Control",
            "TemplateHidden": false,
            "TargetControlType": {
                "__metadata": {
                "type": "Collection(Edm.String)"
                },
                "results": [
                "SearchResults",
                "Content Web Parts"
                ]
            }
        }
    }
]

publish

Type: Boolean Default: false

With this option you can specify if you want to publish files after they are uploaded.

cache

Type: Boolean Default: false

If set to true the plugin caches library locations that already have been processed. Makes the watch tasks quicker.

associatedHtml (only for download actions)

Type: Boolean Default: true

With this property you can specify if you want to download all files (by default set to true) from a folder. This will also download the files that are associated to an HTML template like a page layout, master page and display template. If you set this property to false, the plugin only downloads the HTML files and leaves the ".aspx", ".master" and ".js" files in the folder.

verbose

Type: Boolean Default: false

If you wish to see all the plugin logging you can set this to true.