SharePoint Development - Gulp and Spsave

What is spsave?

In a few words, spsave has a Gulp plug-in that allows you to save files in SharePoint 2013/2016 or SharePoint Online (sorry SharePoint 2010 folks but there is an alternative).  For those who are not familiar with Gulp yet, it’s a Javascript toolkit that is used to automate common repetitive development tasks.  If you are interested in learning more about Gulp, you can get more information about it here.

Why spsave?

Spsave allows developers to build code right in Visual Studio, you have to pay for it, or Visual Code, a free IDE with great features. This also means that developing in SharePoint Designer or manual file uploading is no longer necessary, and if you’ve worked with Designer before you’re probably jumping for joy.

How?

Below are a series of steps you need to take to leverage spsave’s Gulp plugin with Visual Code.

The Prerequisites

1. Download and install NodeJS: https://nodejs.org/en/

2. Download and install Visual Code: https://code.visualstudio.com/download

Setup Your Project

3. Create a folder for your SharePoint project on your PC.

Example of folder
Figure 1 - Example of project folder

4. Then open up Visual Code and open the project folder you created.  Opening a project folder can be accomplished by clicking the File tab in the navigation bar and then selecting the Open Folder option.

5. Now you need to install gulp for the project.  Go to the View tab in the navigation bar and then click the Integrated Terminal option. The Integrated Terminal allows you to issue commands for node, git, etc. for your specific project.  Type in “npm install gulp” into the command prompt.

Npm install gulp
Figure 2 - NPM install gulp

6. Then type in “npm install gulp-spsave” into the command prompt.

7. Now it’s time to setup node package manager for the project.  Type in “npm init” into the command prompt.

npm init
Figure 3 - npm init

8. You will be prompted a series of questions to answer (example in the screenshot below).

npm init questions
Figure 4 - Questions to answer when running npm init

9. When complete, you will see a file called package.json created.

package.json
Figure 5 - Newly created package.json file

10. Create the App folder by clicking the folder icon which is the second icon from the left of the project name. This folder is where you will store your files.

Create Folder
Figure 6 - Create folder button

11. Within the App folder, add a file you wish to upload to SharePoint.  Here is an example file we created:

Example file
Figure 7 - Example file to be uploaded to SharePoint

Note: You may wonder why the example has an .aspx extension.  Depending on your site’s Browser File Handling settings, html files might not render in the browser.  If it has an .aspx extension it will always render in the browser.

Setup Gulp

12. Next you will need to create the gulpfile.js .  Click the New File icon which is the first icon from the left of the project name.

Create new file
Figure 8 - New file button

13. Paste the following into the new file and save as "gulpfile.js":

1.  var gulp = require("gulp");
2.  var spsave = require("gulp-spsave");
3.  var coreOptions = {
4.    siteUrl: '[Your Sharepoint Site]'
5.  };
6.  var creds = {
7.    username: '[Your Username]',
8.    password: '[Your Password]'    
9.  };
10. gulp.task("save", function () {
11.    return gulp.src(["./App/**/*.*"], { base: "App" })
12.        .pipe(spsave({
13.            siteUrl: coreOptions.siteUrl,
14.            folder: "Style%20Library",
15.            flatten: false
16.        }, creds));
17. });
18. gulp.task("default", ["save"], function () { });

14. On line 4 change the siteURL property to the SharePoint site you are working with.

15. Line 11 identifies what files in the project will be copied.  In our example we will copy all the contents within the App folder.

16. Line 14 identifies where the files will be saved to on SharePoint. In this example that will be the Style Library of your SharePoint site.

17. Line 7 and 8 identifies what username and password you use to log into SharePoint.  These are required with spsave.

18. Line 18 identifies that when you run gulp’s build task (“default”), run the “save” task (line 10) which leverages the spsave functionality.

Configure Task Runner Gulp

19. Now we just need to tell Visual Code to run Gulp.  Open the Command Palette by clicking on the View tab in the navigation bar and select the Command Palette option.

20. Type in Configure Task Runner and hit Enter

Configure Task Runner
Figure 9 - Configure Task Runner

20. Select the Gulp option.

Select Gulp
Figure 10 - Select Gulp

 

Run Gulp

22. To run Gulp you can press “Ctrl + Shift + B” which runs the build task and, if your setup is correct, the Gulp task should finish without any errors (example below).

Successful upload
Figure 11 - Example of a successful build

Check SharePoint

23. When you navigate to the Style Library of your SharePoint site you will see the files within the App folder are uploaded.

Files on SharePoint
Figure 12 - File successfully uploaded to SharePoint with gulp-spsave

Example on Github

If you’re interested we have this Visual Code project used in the aforementioned instructions loaded on GitHub at spsave-example.

 

This lays the foundation for you to use gulp-spsave and start developing modern SharePoint applications.  Gulp offers so much more development aids, so keep an eye on our blog for future tips.  At Definitive Logic we know SharePoint Development!

Author: 
David Osorio and John Kerski