• Stars
    star
    172
  • Rank 221,201 (Top 5 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 8 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

๐ŸŒ SharePoint API Proxy for local development

sp-rest-proxy - SharePoint REST API Proxy for local Front-end development tool-chains

NPM

npm version Downloads Build Status FOSSA Status Gitter chat

Allows performing API calls to local Express application with forwarding the queries to a remote SharePoint instance.

Original concept of the proxy was created to show how it could be easy to implements real world data communications for SharePoint Framework local serve mode during web parts debug without deployment to SharePoint tenant. Now the tool is used with multiple teams for modern front-end solutions rapid development.

In a nutshell

Supports SPFx and PnP JS

Supported SharePoint versions

  • SharePoint Online
  • SharePoint On-Prem (2019, 2016, 2013)
  • SharePoint On-Prem 2010 (limited support)

Development paradigms

Supports proxying

  • REST API
  • CSOM requests
  • SOAP web services
  • Custom services
  • Static resources

Proxy modes

  • API Proxy server
  • Socket gateway server
  • Socket gateway client
  • Custom Express apps embed mode

Socket proxying allows to forward API from behind NAT (experimental).

How to use as a module

1. Install NPM module in the project:

npm install sp-rest-proxy

2. Create server.js with the following code:

const RestProxy = require('sp-rest-proxy');

const settings = {
  configPath: './config/private.json', // Location for SharePoint instance mapping and credentials
  port: 8080,                          // Local server port
  staticRoot: './static'               // Root folder for static content
};

const restProxy = new RestProxy(settings);
restProxy.serve();

Configuration parameters cheatsheet

3. Add npm task for serve into package.json:

"scripts": {
  "serve": "node ./server.js"
}

Check if the path to server.js is correct.

4. Run npm run serve.

5. Provide SharePoint configuration parameters.

6. Test local API proxy in action.

How to develop

Install

1. Clone/fork the project:

git clone https://github.com/koltyakov/sp-rest-proxy

2. CMD to the project folder.

3. Install dependencies:

npm install

4. Build:

npm run build

5. Run the server:

npm run serve

or serve in TypeScript directly

npm run ts-serve

Prompts credentials for a SharePoint site.

6. Navigate to http://localhost:8080 (or whatever in settings)

7. Ajax REST calls as if you were in SharePoint site page context:

REST Client Example

8. Tests.

npm run test

Tests Example

Webpack Dev Server

/* webpack.config.js */
const RestProxy = require('sp-rest-proxy');

const port = process.env.WEBPACK_DEV_SERVER_PORT || 9090;

module.exports = {
  // Common Webpack settings
  // ...
  devServer: {
    watchContentBase: true,
    writeToDisk: true,
    port,
    before: (app) => {
      // Register SP API Proxy
      new RestProxy({ port }, app).serveProxy();

      // Other routes
      // ...
    }
  }
};

Rollup Dev Server

For Rollup-based workflows, e.g. Vite tools, please check community plugin: rollup-plugin-sp-rest-proxy.

TypeScript support

In early days of sp-rest-proxy, the library was written in ES6 and used module.exports which was kept after migrating to TypeScript later on for the backward compatibility reasons.

In TypeScript, it's better to import the lib from sp-rest-proxy/dist/RestProxy to get advantages of types:

import RestProxy, { IProxySettings } from 'sp-rest-proxy/dist/RestProxy';

const settings: IProxySettings = {
  configPath: './config/private.json'
};

const restProxy = new RestProxy(settings);
restProxy.serve();

Authentication settings

The proxy provides wizard-like approach for building and managing config files for node-sp-auth (Node.js to SharePoint unattended http authentication).

  • SharePoint Online:
    • User credentials (SAML/ADFS)
    • Add-In Only permissions
    • On-Demand authentication (using Electron popup)
  • SharePoint 2019, 2016, 2013:
    • User credentials (NTLM, NTLM v2)
    • ADFS user credentials
    • Form-based authentication (FBA)
    • Form-based authentication (Forefront TMG)
    • Add-In Only permissions
    • On-Demand authentication (using Electron popup)
  • SharePoint 2010:
    • User credentials (NTLM, NTMLv2)
    • Form-based authentication (FBA)
    • Form-based authentication (Forefront TMG)

For more information please check node-sp-auth credential options and wiki pages. Auth settings are stored inside ./config/private.json.

PnPjs

sp-rest-proxy works with PnPjs (check out brief notice how to configure).

PnP JS + sp-rest-proxy

Load page context helper

sp-rest-proxy includes helper method for configuring page context - loadPageContext.

import { loadPageContext } from 'sp-rest-proxy/dist/utils/env';
import { Web } from '@pnp/sp';

// loadPageContext - gets correct URL in localhost and SP environments
loadPageContext().then(async () => {

  // In both localhost and published to SharePoint page
  // `_spPageContextInfo` will contain correct info for vital props

  // PnPjs's Web object should be created in the following way
  const web = new Web(_spPageContextInfo.webAbsoluteUrl);

  // Then goes ordinary PnPjs code
  const batch = web.createBatch();

  const list = web.getList(`${_spPageContextInfo.webServerRelativeUrl}/List/ListName`);
  const entityName = await list.getListItemEntityTypeFullName();

  [1, 2, 3, 4].forEach((el) => {
    list.items.inBatch(batch).add({
      Title: `${el}`
    }, entityName);
  });

  await batch.execute();
  console.log('Done');

}).catch(console.warn);

JSOM (SharePoint JavaScript Object Model)

JSOM can be used in local development mode with sp-rest-proxy with some additional setup.

The local development workbench page should contain JSOM init scripts:

<script type="text/javascript" src="/_layouts/15/1033/initstrings.js"></script>
<script type="text/javascript" src="/_layouts/15/init.js"></script>
<script type="text/javascript" src="/_layouts/15/MicrosoftAjax.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.core.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.runtime.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.js"></script>

Check out the example.

SharePoint Framework

Blog post article with setting up SPFx and Proxy

Use cases

  • Client side applications development with local serve, but real data from SharePoint
  • SharePoint Framework in local workbench with real data
  • Client applications integration test automation scenarios

Usage with Docker

License

FOSSA Status

More Repositories

1

gosip

โšก๏ธ SharePoint SDK for Go
Go
141
star
2

generator-sppp

๐Ÿพ SP Pull-n-Push - Yeoman generator for SharePoint client-side applications
TypeScript
64
star
3

sppull

๐Ÿ“Ž Download files from SharePoint document libraries using Node.js without hassles
TypeScript
45
star
4

mvp-monitor

๐Ÿ“Š Microsoft MVPs Monitor
PowerShell
32
star
5

sp-pnp-node

SharePoint JavaScript Core Library wrapper helper for Node.js
TypeScript
25
star
6

sp-live-reload

SharePoint pages live reload module for client side development
TypeScript
23
star
7

sp-jsom-node

๐Ÿšด SharePoint JavaScript Object Model for Node.js
JavaScript
21
star
8

node-sp-auth-config

๐Ÿ”ง Config options builder for node-sp-auth (SharePoint Authentication in Node.js)
TypeScript
20
star
9

sp-metadata

๐Ÿ”ฌ SharePoint Metadata Tracker
Go
18
star
10

cq-source-sharepoint

๐Ÿ”Œ CloudQuery SharePoint Source Plugin
Go
17
star
11

sp-build-tasks

๐Ÿ‘ท SharePoint front-end projects automation and tasks tool-belt
TypeScript
16
star
12

sp-screwdriver

Adds missing and abstracts SharePoint APIs for transparent usage in Node.js applications
TypeScript
15
star
13

az-fun-go-sp

Azure Functions Golang & SharePoint Sample
Go
13
star
14

azure-openai-sample

Azure OpenAI sample
TypeScript
13
star
15

pnp-upload

SharePoint: Large files upload example using PnPjs from Node.js
TypeScript
13
star
16

sp-download

SharePoint files download client in Node.js
TypeScript
13
star
17

cpass

๐Ÿ” Simple secure string password convertor
TypeScript
12
star
18

spsync

๐Ÿชข Go library for robust cloud native SharePoint Lists synchronization or backup
Go
10
star
19

sppurge

Delete files from SharePoint document libraries using Node.js without hassles
TypeScript
9
star
20

gosip-docs

๐Ÿ“š Docs: SharePoint authentication, HTTP client & fluent API wrapper for Go (Golang)
9
star
21

sp-modernizer-kit

SharePoint Online classic sites modernizer kit
TypeScript
7
star
22

SPSyncN

SharePoint .Net assets sync via Node.js
JavaScript
6
star
23

sp-time-machine

โณ Incrementally backup SharePoint Lists across tenants
Go
6
star
24

gosip-sandbox

๐Ÿฃ Sandbox: Samples, experiments for Gosip client
Go
6
star
25

github-notify

:octocat: GitHub Notifications for desktop
Go
6
star
26

spvault

SharePoint Authentication Vault gRPC Server
Go
5
star
27

sp-auth-puppeteer-sample

Puppeteer & node-sp-auth example
TypeScript
5
star
28

SPAuthN

SharePoint .Net auth via Node.js
C#
5
star
29

sp-auth-electron-sample

Electron & node-sp-auth example
TypeScript
5
star
30

node-sharepoint-examples

Node.js SharePoint Examples
TypeScript
5
star
31

on-el-resize

On HTML element resize event fire helper
TypeScript
4
star
32

sp-sig-20180705-demo

PnP and SharePoint SIG / July 5th, 2018 / Demo Examples (List Items System Update options in Modern SPO Stack)
TypeScript
3
star
33

spfx-styled-components-sample

Styled Components and SPFx theming sample (SIG 2020/06/04)
TypeScript
3
star
34

spday-spb-2018-js-usecases

SharePoint Day 2018 - SharePoint JS API Consumption Examples
TypeScript
2
star
35

blogs-technet-grabber

blogs.technet.microsoft.com grabber
TypeScript
1
star
36

PnP-JS-Core-Debug

PnP-JS-Core Quick Debug in Node JS - a service project to allow quick interactive testing while contributing to sp-pnp-js
TypeScript
1
star
37

PnPjs-Debug

PnPjs Quick Debug in Node JS - a service project to allow quick interactive testing while contributing to PnPjs
TypeScript
1
star
38

sp-sig-20170608-demo

PnP and SharePoint SIG / June 8th, 2017 / Demo Examples
TypeScript
1
star
39

node-sp-auth-troubleshoot

Node.js SharePoint Auth Troubleshooting
JavaScript
1
star