SharePoint REST API Proxy

This project provides a SharePoint REST API proxy server for SharePoint operations. It acts as a direct local/dev proxy to SharePoint REST API with Azure Entra authentication, allowing you to use live SharePoint data with PnP.js and other SharePoint REST clients during app development.

Features

• Direct SharePoint REST API - forwards requests directly to SharePoint for full compatibility
• Multi-site tenant support - access any SharePoint site in your tenant through one proxy
• OAuth2 authentication via Azure AD app registration with authorization code flow
• Full SharePoint REST API compatibility - supports all operations that work with sp-rest-proxy
• PnP.js compatible - works seamlessly with existing PnP.js code
• Node.js v24+ support - compatible with all LTS and current Node.js versions

Node.js Compatibility

This proxy server supports Node.js 18.x and higher, including the latest Node.js v24+.

Recent Improvements:

• v1.0.8+: Fixed main module detection to work reliably across all Node.js versions (v18-v24+)
• Uses fileURLToPath and path.resolve() for robust ES module compatibility
• No breaking changes - existing code continues to work as expected

Setup

1. Azure AD App Registration

Your app registration should have:

• Application Type: Public client (native)
• Tenant ID
• Application ID
• Permissions:
  • SharePoint AllSites.FullControl (Delegated) or similiar scopes

2. Configuration

Add a file in the root of your project, server.js:

import RestProxy from 'sp-proxy-server';
 
const settings = {
  "siteUrl": "https://somesite.sharepoint.com",
  "tenantId": "yourtenantid",
  "clientId": "yourclientid",
  "scopes": ["AllSites.FullControl"]
}
 
const restProxy = new RestProxy(settings);
restProxy.serve();

Note: The siteUrl is set to your tenant root URL to enable multi-site access. Individual site URLs are specified in your client application requests.

Usage

Start the SharePoint REST API Proxy Server

node server.js

On first run, you'll need to authenticate:

1. The server will automatically open your browser for OAuth2 authentication
2. Sign in with your Microsoft account that has access to SharePoint
3. Grant the requested permissions
4. The server will start once authenticated and display the proxy URL

Configure Your Client Application

For PnP.js, configure your service to use the proxy:

// In your SharePointService.js or similar
import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/lists";
import "@pnp/sp/items";

// For development (using proxy)
const sp = spfi("http://localhost:8081/sites/your-site-name");

// For production 
// const sp = spfi("https://yourtenant.sharepoint.com/sites/your-site-name");

Multi-site Usage: You can access different SharePoint sites by changing the URL:

// Access different sites in your tenant
const sp1 = spfi("http://localhost:8081/sites/site1"); 
const sp2 = spfi("http://localhost:8081/sites/site2");

Start Your Development App

In a separate terminal:

npm run dev

API Endpoints Supported

The proxy server forwards ALL SharePoint REST API requests directly to SharePoint, maintaining full compatibility.

Troubleshooting

Authentication Issues

• Ensure your app registration has the correct delegated permissions (AllSites.FullControl recommended)
• Make sure you're signing in with an account that has access to SharePoint sites
• Check that the tenant ID and client ID are correct in config/private.json
• If authentication fails, restart the server to re-authenticate

Site Access Issues

• Verify the site name in your URLs matches the actual SharePoint site URL
• Ensure your account has appropriate permissions to the specific SharePoint site
• Check that the tenant URL is correct
• For new sites, wait a few minutes for permissions to propagate

Proxy Connection Issues

• Ensure the proxy server is running on http://localhost:8081
• Check that no other services are using port 8081
• Verify your client application is configured to use http://localhost:8081/sites/[site-name]

Development vs Production

• In development, the proxy runs on localhost:8081
• Configure your client to use the proxy URL: http://localhost:8081/sites/[site-name]
• In production, switch back to direct SharePoint URLs: https://yourtenant.sharepoint.com/sites/[site-name]
• The proxy enables development without exposing SharePoint credentials

Key Benefits

• No API Translation: Direct proxy to SharePoint REST API ensures 100% compatibility
• Multi-Site Support: Access any site in your tenant through one authenticated proxy
• Zero Code Changes: Drop-in replacement for sp-rest-proxy
• Modern Authentication: OAuth2 with automatic browser-based login
• Full Feature Support: All SharePoint REST API features work without limitations

Files

• sp-proxy-server.js - Main SharePoint REST API proxy server implementation