SPA Series: Using sp-rest-proxy for local web development against real SharePoint data

A very interesting tool called sp-rest-proxy enables us to do local web development against real SharePoint data. All REST api requests are proxied to the real SharePoint in the context of a configured site under the credentials of a configured username and password.

Install sp-rest-proxy using: npm install sp-rest-proxy --save-dev. See sp-rest-proxy for the documentation.

As described in the documentation create a file server.js with the following contents:

Note that instead of using port 8080 as described in the documentation we used port 8081... with a reason: the sp-rest-proxy tool contains a UI to test our api REST requests, and that tool runs under port 8080.

The app under development lives in static/index.html:

End code of file static/index.html.

The code is written in a way that it will work for local development and for hosting within a document library in SharePoint as described in SPA Series: Building full screen single page web applications on SharePoint.

We also added a new and improved deploy.js script:

End code of file deploy.js.

Note that the deploy script loads a configuration file from config/_private.conf.json which contains the site to deploy to and the credentials to use for deployment. This file is excluded from sourcecontrol (through .gitignore) because it contains personal settings, but the file (which is generated through a set of questions when starting the local website) contains something like:

{
    "siteUrl":"https://macaw-my.sharepoint.com/personal/serge_macaw_nl/apps",
    "username":"serge@macaw.nl",
    "password":"<my password>"
}

The password is encrypted on creation of the site, but a plain password works as well.

During the deployment two things are done:

  1. the contents of the file static/index.html is loaded and all occurences of http://localhost:8081 are replaced with the url of the SharePoint site we will deploy to.
  2. the contents of the file is uploaded in the document library apppages in the folder showtitlerest with the name index.aspx.

We extend the npm package.json script with some commands:

End  of file package.json.

We can now execute the following commands:

  1. npm run serve - start a local website with our app on http://localhost:8081/index.html. On first run it asks for the url to the SharePoint site sp-rest-proxy makes a proxy for, a domain (leave empty for SharePoint Online), a username (in the format name@mycompany.com for SharePoiint Online) and a password. Persist the configuration so the settings can be used by the deploy script as well.
  2. npm run api - start a test site at http://localhost:8080 that is part of sp-rest-proxy to test api requests.
  3. npm run deploy - deploy our app to the apppages document library in a folder showtitlerest. The app is available under the url https://<yoursharepointsite>/apppages/showtitlerest/index.aspx. For me this url is https://macaw-my.sharepoint.com/personal/serge_macaw_nl/apps/apppages/showtitlerest/index.aspx.

Conclusion

this concludes this blog post. What did we accomplish:

  • We can do local web development against the content of a live SharePoint site. Api calls can be made through the url http://localhost:8081/_api/... On deployment this url is replaced by the correct site url we deploy to.
  • We can test api calls in a test page available on http://localhost:8080.
  • We can deploy our resulting app page to the SharePoint site.

The sample code can be found in the GitHub repository https://github.com/svdoever/sharepoint-progressive-web-apps in the folder ShowTitleRestWithProxy.

SharePoint SPA Series blog posts

No Comments