# gulp-spsave

> Gulp pluging for saving files in SharePoint.

Latest version **4.0.0** (published 2020-07-27) · 0 weekly downloads

## Install

```sh
npm install gulp-spsave
pnpm add gulp-spsave
yarn add gulp-spsave
bun add gulp-spsave
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2020-07-27 |
| First published | 2015-08-16 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4.0.0 |
| Dependencies | 7 |
| Unpacked size | 181.9 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 50 |
| Author | Sergei Sergeev |
| Maintainers | s-kainet |

## Links

- npm: https://www.npmjs.com/package/gulp-spsave
- Repository: https://github.com/s-KaiNet/gulp-spsave
- Homepage: https://github.com/s-KaiNet/gulp-spsave#readme
- Issues: https://github.com/s-KaiNet/gulp-spsave/issues
- npm.io page: https://npm.io/package/gulp-spsave

## Dependencies (7)

- [path](https://npm.io/package/path.md) ^0.12.7
- [spsave](https://npm.io/package/spsave.md) ^4.0.0
- [through2](https://npm.io/package/through2.md) 4.0.2
- [plugin-error](https://npm.io/package/plugin-error.md) ^1.0.1
- [lodash.assign](https://npm.io/package/lodash.assign.md) ^4.2.0
- [node-notifier](https://npm.io/package/node-notifier.md) ^7.0.2
- [lodash.defaults](https://npm.io/package/lodash.defaults.md) ^4.2.0

## Recent versions

- 4.0.0 (latest) — 2020-07-27
- 3.1.1 — 2018-06-26
- 3.1.0 — 2017-08-09
- 3.0.0 — 2016-10-08
- 2.0.2 — 2016-07-17
- 2.0.1 — 2016-06-08
- 2.0.0 — 2016-06-01
- 1.0.6 — 2016-01-04
- 1.0.5 — 2015-12-08
- 1.0.4 — 2015-12-08
- 1.0.3 — 2015-12-08
- 1.0.2 — 2015-10-11
- 1.0.1 — 2015-09-26
- 1.0.0 — 2015-09-11
- 0.0.2 — 2015-08-16
- … 1 more at https://npm.io/package/gulp-spsave/versions

## README

# gulp-spsave 

[![NPM](https://nodei.co/npm/gulp-spsave.png?mini=true)](https://nodei.co/npm/gulp-spsave/)  
[![npm version](https://badge.fury.io/js/gulp-spsave.svg)](https://badge.fury.io/js/gulp-spsave)

### Need help on SharePoint with Node.JS? Join our gitter chat and ask question! [![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/sharepoint-node/Lobby)

Gulp plugin for [spsave](https://github.com/s-KaiNet/spsave) - save files in SharePoint using node.js easily. 

----------

## How to use:
#### Install:
```bash
npm install gulp-spsave --save-dev
```
#### Usage:

```javascript
var spsave = require('gulp-spsave');
var gulp = require('gulp');

gulp.task("default", function(){
  return gulp.src("./build/*.js")
             .pipe(spsave(coreOptions, creds));
});
```

## Options:   

Exactly the same as for [spsave](https://github.com/s-KaiNet/spsave), except file content options (because the file is piped through the gulp stream).  
That means no need to provide such options as `fileName`, `fileContent`, `glob`, `file`, `base` (`base` can be provided for the `gulp.src`, see samples below).  
I recommend you look at the [spsave](https://github.com/s-KaiNet/spsave) page to get a better understanding.

#### Core options (passed to `spsave`):
The same as for [spsave core options](https://github.com/s-KaiNet/spsave#core-options) plus two additional options exclusive to `gulp-spsave`:
 - `folder` - required string, SharePoint folder to upload file to (can be the url to document library)
 - `flatten` - boolean, default true, when true all files will be uploaded to `folder` provided, regardles of the file physical location. For example, if folder equal to `MyAppAssets` and you pipe two files `app/controllers/HomeCtrl.js` and `app/templates/home.html`, then `MyAppAssets` will contain both `HomeCtrl.js` and `home.html` in the root.   
	 If `flatten` is false, `gulp-spsave` will look for base for the file and will use this base for upload file in a particular folder (or create this folder automatically if required). See [gulp API docs](https://github.com/gulpjs/gulp/blob/master/docs/API.md), `gulp.src(globs[, options])` and [glob2base](https://github.com/contra/glob2base).   

#### Credentials:

`gulp-spsave` implicitly depends on another module used for SharePoint authentication from node js - [node-sp-auth](https://github.com/s-KaiNet/node-sp-auth). For credentials param you need to pass exactly the same object, as for `node-sp-auth` [credentialsOptions object](https://github.com/s-KaiNet/node-sp-auth#params). That also means that `gulp-spsave` supports all authentication options supported by `node-sp-auth`. See examples below for more info.  
You can also pass a `null` as credentials, in that case `gulp-spsave` will ask you for credentials and will store your credentials in a user folder in an encrypted manner (everything is handled by `node-sp-auth` actually). 

Examples:
--    

Imagine we have `settings.js` which stores all sensitive information for us (credential information, client id\client secret etc.): 

```javascript
module.exports = {
    username: "[user]",
    password: "[pass]"
}
```

1.Watch for file changes in scripts, then bundle, minify, whatever, and upload to SharePoint automatically:

----------


```javascript
//sensitive data stored in external file:
var creds = require("./settings.js");
gulp.task("buildJS", function(){
	return gulp.src("./Scripts/**/*.js")
	.pipe(concat())
	.pipe(uglify())
	.pipe(gulp.dest("./build"));
});

gulp.task("copyToSharePoint", ["buildJS"], function(){
	return gulp.src("./build/*.js")
		.pipe(spsave({
			siteUrl: settings.siteUrl,
			folder: "YourAppAssets/js"
		}, creds));
});

gulp.task("watch", function(){
	gulp.watch(["./Scripts/**/*.js"], ["copyToSharePoint"]);
});
```  
2.Save all files from `App/build` to SharePoint:

----------

```javascript
//sensitive data stored in external file:
var creds = require("./settings.js");
gulp.task("spsave", function () {
	return gulp.src(["App/build/*.*"])
		.pipe($.spsave({
			siteUrl: settings.siteUrl,
			folder: "App/build",
			flatten: true
		}, creds));
});
```  
3.Watch all javascript file changes in `ng` (stands for angular) folder and upload that file automatically in SharePoint with preserved folder structure: 

----------


```javascript
//sensitive data stored in external file:
var creds = require("./settings.js");
gulp.watch("App/ng/**/*.js", function (event) {
		gulp.src(event.path)
			.pipe($.spsave({
				siteUrl: settings.siteUrl,
				folder: "AppAssets",
				flatten: false
			}, creds));
	});
```  
In this sample `base` will be equal to `App/ng`. If file path is `App/ng/controllers/HomeCtrl.js`, then it will saved under `AppAssets/controllers/HomeCtrl.js` (if some folders are missing, they will be created by `spsave` automatically). Next sample demonstrate how can you save it under `AppAssets/ng/controllers/HomeCtrl.js` 

4.You can also explicitly provide `base` for `gulp.src`: 

----------
 
```javascript
//sensitive data stored in external file:
var creds = require("./settings.js");
gulp.watch("App/ng/**/*.js", function (event) {
		gulp.src(event.path, { base: "App" })
			.pipe($.spsave({
				siteUrl: settings.siteUrl,
				folder: "AppAssets",
				flatten: false
			}, creds));
	});
```  
In this case file be saved under `AppAssets/ng/controllers/HomeCtrl.js` path.   

5.Upload search display template with metadata:

----------

```javascript
//sensitive data stored in external file:
var creds = require("./settings.js");
gulp.watch("App/search/Item_Display.js", function (event) {
		gulp.src(event.path)
			.pipe($.spsave({
				siteUrl: settings.siteUrl,
				folder: "_catalogs/masterpage/Display Templates/Search",
				flatten: true,
				filesMetaData: [{
					fileName: "Item_Display.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));
	});
```  
...and any other scenarios you need.

For list of all options for the `spsave` refer to the [git hub repository](https://github.com/s-KaiNet/spsave).  

## Integration testing:
1. Rename file `/test/integration/config.sample.js` to `config.js`.
2. Update information in `config.js` with appropriate values (urls, credentials, environment).
3. Run `npm run test-int`.

Known Issues
--

When heavily utilizing watchers along with `gulp-spsave` you may see errors "Save conflict" or "Cobalt error". [spsave](https://github.com/s-KaiNet/spsave) tries to recover from these errors by trying to re-upload the file once or twice again. But usually it's a good idea to use [gulp-plumber](https://github.com/floatdrop/gulp-plumber) or similar tool in order to make sure that your watchers will not be broken when errors occur.   
Normally you can do the following in your `gulpfile.js`:   

```javascript 
var plumber = require("gulp-plumber");
var onError = function (err) {
	console.log(err);
	this.emit("end");
};
gulp.watch(["App/index.html"], function (event) {
		return gulp.src(event.path, { base: "App" })
			.pipe(plumber({
				errorHandler: onError
			}))
			.pipe(spsave(settings));
	});

```

In case of error, your watch will remain up and running regardless of the error.

---
_Source: https://npm.io/package/gulp-spsave · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._