Recipes.md

spsave recipes

On this page you can find different options supported by spsave.

As you may noted from README, spsave supports all authentication options node-sp-auth provides. All you need is to pass appropriate credentials object. Refer to node-sp-auth credentialsOptions object.
For example SharePoint on-premise addin only authentication with spsave (consider creds variable):

var coreOptions = {
  siteUrl: '[sp url]'
};
var creds = {
  clientId: '[clientId]',
  issuerId: '[issuerId]',
  realm: '[realm]',
  rsaPrivateKeyPath: '[rsaPrivateKeyPath]',
  shaThumbprint: '[shaThumbprint]'
};

var fileOptions = {
  folder: 'SiteAssets',
  fileName: 'file.txt',
  fileContent: 'hello world'
};
spsave(coreOptions, creds, fileOptions)
.then(function(){
    console.log('saved');
})
.catch(function(err){
    console.log(err);
});

... or SharePoint online user credentials authentication:

var coreOptions = {
  siteUrl: '[sp url]'
};
var creds = {
  username: '[user@organization.onmicrosoft.com]',
  password: '[password]'
};

var fileOptions = {
  folder: 'SiteAssets',
  fileName: 'file.txt',
  fileContent: 'hello world'
};
spsave(coreOptions, creds, fileOptions)
.then(function(){
    console.log('saved');
})
.catch(function(err){
    console.log(err);
});

as simple as that.

Lets assume we have core options like siteUrl and creds. The most interesting options are file content option, so lets take a closer look to all possible scenarios.

As you may know there are three types of file content options - file content, glob, vinyl file.

File content options

Save file using its name and content. Additionally perform major checkin:

spsave({
  siteUrl: '[sp url]',
  checkin: true,
  checkinType: 1
}, 
creds, {
  folder: 'SiteAssets',
  fileName: 'file.txt',
  fileContent: 'hello world'
})

Result:

New file file.txt will be uploaded to [sp site url]/SiteAssets. If SiteAssets is document library, file will be visible as new file in document library.
If SiteAssets folder doesn't exist, spsave will create that folder. Also the file will be checked in with major version.

Save file using its name and content, update metadata for the file:

spsave({
  siteUrl: '[sp url]',  
  filesMetaData: [{
          fileName: 'file.txt',
          metadata: {
            '__metadata': { type: 'SP.Data.SiteAssetsItem' },
            Title: title
          }
        }]
}, creds, {
  folder: 'SiteAssets',
  fileName: 'file.txt',
  fileContent: 'hello world'
})

Result:

New file file.txt will be uploaded to [sp site url]/SiteAssets. If SiteAssets is document library, file will be visible as new file in document library.
If SiteAssets folder doesn't exist, spsave will create that folder. Field "Title" will be updated with title provided.

Upload search display template to master page gallery:

spsave({
  siteUrl: '[sp url]',
  filesMetaData: [{
          fileName: 'Item_Template.js',
          metadata: {
            '__metadata': { type: 'SP.Data.OData__x005f_catalogs_x002f_masterpageItem' },
            Title: 'SPSave Display Template',
            DisplayTemplateLevel: 'Item',
            TargetControlType: {
              '__metadata': {
                'type': 'Collection(Edm.String)'
              },
              'results': [
                'SearchResults'
              ]
            },
            ManagedPropertyMapping: `'Title':'Title','Path':'Path','Description':'Description'`,
            ContentTypeId: '0x0101002039C03B61C64EC4A04F5361F38510660500A0383064C59087438E649B7323C95AF6',
            TemplateHidden: false
          }
        }]
}, creds, {
  folder: '_catalogs/masterpage/Display Templates/Search',
  fileName: 'Item_Template.js',
  fileContent: '<javascript content>'
})

Result:

New display template Item_Template.js will be uploaded to master page gallery. Metadata for the template will be updated.

Save binary file using nodejs fs.readFileSync function, show notificatin upon upload (or error if any):

spsave({
  siteUrl: '[sp url]',
  notification: true
}, creds, {
  folder: 'SiteAssets/app/templates',
  fileName: 'file.txt',
  fileContent: fs.readFileSync('file.txt')
})

Result:

New file file.txt will be uploaded to [sp site url]/SiteAssets/app/templates/. If SiteAssets/app/templates/ doesn't exists, full folders hierarchy wil be created by spsave

Glob options

Save file by its path (file content and file name will be extracted automatically):

spsave({
  siteUrl: '[sp url]'
}, creds, {
  glob: 'myapp/files/file.txt',
  folder: 'SiteAssets'
})

Result:

New file file.txt will be uploaded to [sp site url]/SiteAssets

Save file by its path with base option:

spsave({
  siteUrl: '[sp url]'
}, creds, {
  glob: 'myapp/data/files/file.txt',
  folder: 'SiteAssets',
  base: 'myapp'
})

Result:

New file file.txt will be uploaded to [sp site url]/SiteAssets/data/files (because of base option)

Save file by its path without folder option:

spsave({
  siteUrl: '[sp url]'
}, creds, {
  glob: 'myapp/data/files/file.txt',
  base: 'myapp'
})

Result:

New file file.txt will be uploaded to [sp site url]/data/files/ (because of folder is missing, data becomes root folder)

Save multiple files by mask, preserve folder structure (base options is used):

spsave({
  siteUrl: '[sp url]'
}, creds, {
  glob: 'myapp/**/*.*',
  base: 'myapp',
  folder: 'SiteAssets'
})

Result:

All files from myapp local folder will be uploaded to SiteAssets folder. spsave will preserve folder structure if myapp has any subfolders.

Save multiple files by mask, flatten structure:

spsave({
  siteUrl: '[sp url]'
}, creds, {
  glob: 'myapp/**/*.*',
  folder: 'SiteAssets'
})

Result:

All files from myapp local folder will be uploaded to SiteAssets folder using flatten structure (base option is missing).

Save multiple different files:

spsave({
  siteUrl: '[sp url]'
}, creds, {
  glob: ['myapp/files/file.txt', 'myapp/templates/home.html'],
  folder: 'SiteAssets'
})

Result:

Two files will be uploaded to [sp site url]/SiteAssets - file.txt and home.html

Vinyl file options:

Pipe vinyl file and save it to SharePoint:

var vfs = require('vinyl-fs');
var map = require('map-stream');

vfs.src('files/file.txt')
  .pipe(map(function(file, cb) {
    spsave({
      siteUrl: '[sp url]'
    }, creds, {
      file: file,
      folder: 'SiteAssets'
    })
    .then(function(){ console.log('success'); })
    .finally(function(){ cb(); });

Result:

New file file.txt will be uploaded to [sp site url]/SiteAssets

Pipe vinyl file with base option and upload to subfolder using base:

var vfs = require('vinyl-fs');
var map = require('map-stream');

vfs.src('myapp/data/files/file.txt', { base: 'myapp' })
  .pipe(map(function(file, cb) {
    spsave({
      siteUrl: '[sp url]'
    }, creds, {
      file: file,
      folder: 'SiteAssets'
    })
    .then(function(){ console.log('success'); })
    .finally(function(){ cb(); });

Result:

New file file.txt will be uploaded to [sp site url]/SiteAssets/data/files