{"id":21655893,"url":"https://github.com/koltyakov/sp-pnp-node","last_synced_at":"2025-08-21T06:31:23.305Z","repository":{"id":39578726,"uuid":"91610137","full_name":"koltyakov/sp-pnp-node","owner":"koltyakov","description":"SharePoint JavaScript Core Library wrapper helper for Node.js","archived":false,"fork":false,"pushed_at":"2024-09-06T09:00:22.000Z","size":1062,"stargazers_count":25,"open_issues_count":13,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-15T11:04:29.604Z","etag":null,"topics":["api","authentication","client","javascript","nodejs","rest-api","sharepoint","sp-pnp-js","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koltyakov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-17T18:54:25.000Z","updated_at":"2024-03-31T03:34:17.000Z","dependencies_parsed_at":"2024-10-12T22:01:35.733Z","dependency_job_id":"527c2b43-9a21-4565-a79e-d985ca30c139","html_url":"https://github.com/koltyakov/sp-pnp-node","commit_stats":{"total_commits":80,"total_committers":4,"mean_commits":20.0,"dds":0.5875,"last_synced_commit":"172c0d9360e24a2e241f38a7e3e83e158d78fc4b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-pnp-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-pnp-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-pnp-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-pnp-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koltyakov","download_url":"https://codeload.github.com/koltyakov/sp-pnp-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230494921,"owners_count":18235046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","authentication","client","javascript","nodejs","rest-api","sharepoint","sp-pnp-js","typescript"],"created_at":"2024-11-25T08:37:43.455Z","updated_at":"2024-12-19T20:08:38.927Z","avatar_url":"https://github.com/koltyakov.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sp-pnp-node - PnPjs's auth client factory for Node.js\r\n\r\n[![NPM](https://nodei.co/npm/sp-pnp-node.png?mini=true\u0026downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/sp-pnp-node/)\r\n\r\n[![npm version](https://badge.fury.io/js/sp-pnp-node.svg)](https://badge.fury.io/js/sp-pnp-node)\r\n[![Downloads](https://img.shields.io/npm/dm/sp-pnp-node.svg)](https://www.npmjs.com/package/sp-pnp-node)\r\n![Build Status](https://koltyakov.visualstudio.com/SPNode/_apis/build/status/sp-pnp-node?branchName=master)\r\n![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)\r\n\r\n\u003e Consider using [pnp-auth](https://github.com/SharePoint-NodeJS/pnp-auth) as a successor which soaked the best of `sp-pnp-node` and `node-pnp-sp` libraries. I'm keeping `sp-pnp-node` not archived and update it from time to time only because of some production implementations which I'm too lazy to migrate to `pnp-auth` right away.\r\n\r\n`sp-pnp-node` provides a simple way for using [`PnPjs`](https://github.com/pnp/pnpjs) in Node.js with support of various authentication strategies.\r\n\r\n## About PnPjs\r\n\r\nPnPjs Client Side Libraries for Microsoft 365 was created to help developers by simplifying common operations within SharePoint and the SharePoint Framework. Currently it contains a fluent API for working with the full SharePoint REST API as well as utility and helper functions. This takes the guess work out of creating REST requests, letting developers focus on the what and less on the how.\r\n\r\n## Supported SharePoint versions\r\n\r\n- SharePoint Online\r\n- SharePoint On-Prem (2019, 2016, 2013)\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install sp-pnp-node @pnp/pnpjs@^1.3.11\r\n```\r\n\r\n## Usage examples\r\n\r\n### Minimal setup\r\n\r\nCan be as simple as 5 lines of code:\r\n\r\n```typescript\r\nimport { Web } from '@pnp/sp';\r\nimport { PnpNode } from 'sp-pnp-node';\r\n\r\nnew PnpNode().init().then(settings =\u003e {\r\n\r\n  const web = new Web(settings.siteUrl);\r\n  /// ... // \u003c\u003c\u003c Here goes PnP JS Core code\r\n\r\n}).catch(console.log);\r\n```\r\n\r\n![demo](https://raw.githubusercontent.com/koltyakov/sp-pnp-node/master/docs/demo.gif)\r\n\r\n`sp-pnp-node` has two modes:\r\n\r\n- ambient init - wraps `PnPjs` with promise based auth wizard helper\r\n- factory - `fetchClientFactory` implementation\r\n\r\n_When to use ambient init_: in scripts with user interaction involved when there is no information about authentication and target invironment before script is executed. SharePoint url and the creds are prompted in a console.\r\n\r\nIn CI/CD scenarios, factory approach is recommended over interactive console as it can lead to a task stuck.\r\n\r\n### TypeScript\r\n\r\n#### Ambient init example\r\n\r\n```typescript\r\nimport { Web } from '@pnp/sp';\r\nimport { PnpNode, IPnpNodeSettings } from 'sp-pnp-node';\r\n\r\nconst optionalInitSettings: IPnpNodeSettings = {\r\n  // ...\r\n};\r\n\r\nnew PnpNode(optionalInitSettings).init().then((settings: IPnpNodeSettings) =\u003e {\r\n\r\n  // Here goes PnP JS Core code \u003e\u003e\u003e\r\n\r\n  const web = new Web(settings.siteUrl);\r\n  // Any SPWeb url can be used for `new Web(...)`\r\n  // not necessarily which is provided in `optionalInitSettings`\r\n\r\n  // Get all list example\r\n  web.lists.get()\r\n    .then(lists =\u003e {\r\n      console.log(lists.map(list =\u003e list.Title));\r\n    })\r\n    .catch(console.log);\r\n\r\n  // \u003c\u003c\u003c Here goes PnP JS Core code\r\n\r\n}).catch(console.log);\r\n```\r\n\r\n#### Factory example\r\n\r\n```typescript\r\nimport * as pnp from '@pnp/sp';\r\nimport { PnpNode, IPnpNodeSettings } from 'sp-pnp-node';\r\n\r\nconst config = require('../config/private.json');\r\n\r\nconst pnpNodeSettings: IPnpNodeSettings = {\r\n  // siteUrl - Optional if baseUrl is in pnp.setup or in case of `new Web(url)`\r\n  siteUrl: config.siteUrl,\r\n  authOptions: config\r\n};\r\n\r\npnp.sp.setup({\r\n  sp: {\r\n    fetchClientFactory: () =\u003e new PnpNode(pnpNodeSettings),\r\n    // baseUrl - Optional if siteUrl is in IPnpNodeSettings or in case of `new Web(url)`\r\n    baseUrl: config.siteUrl\r\n  }\r\n});\r\n\r\npnp.sp.web.get()\r\n  .then(console.log)\r\n  .catch(console.log);\r\n\r\n// Or\r\n\r\n/*\r\nnew Web('http://adhoc.url/sites/site').get()\r\n  .then(console.log)\r\n  .catch(console.log);\r\n*/\r\n```\r\n\r\n### JavaScript\r\n\r\n```javascript\r\nconst { Web } = require('@pnp/sp');\r\nconst { PnpNode } = require('sp-pnp-node');\r\n\r\nnew PnpNode().init().then(settings =\u003e {\r\n\r\n  // Here goes PnP JS Core code \u003e\u003e\u003e\r\n\r\n  const web = new Web(settings.siteUrl);\r\n\r\n  // Get all content types example\r\n  web.contentTypes.get()\r\n    .then(cts =\u003e {\r\n      console.log(cts.map(ct =\u003e {\r\n        return {\r\n          name: ct.Name,\r\n          description: ct.Description\r\n        };\r\n      }));\r\n    })\r\n    .catch(console.log);\r\n\r\n  // \u003c\u003c\u003c Here goes PnP JS Core code\r\n\r\n}).catch(console.log);\r\n```\r\n\r\n### OData Metadata modes\r\n\r\n```typescript\r\nimport { sp } from '@pnp/sp';\r\nimport { PnpNode, IPnpNodeSettings } from 'sp-pnp-node';\r\n\r\nnew PnpNode().init().then((settings: IPnpNodeSettings) =\u003e {\r\n\r\n  sp.setup({\r\n    sp: {\r\n      headers: {\r\n        // 'Accept': 'application/json;odata=verbose'\r\n        'Accept': 'application/json;odata=minimalmetadata'\r\n        // 'Accept': 'application/json;odata=nometadata'\r\n      }\r\n    }\r\n  });\r\n\r\n  // ...\r\n\r\n}).catch(console.log);\r\n```\r\n\r\n## Initiation settings\r\n\r\n```typescript\r\nimport { PnpNode } from 'sp-pnp-node';\r\n\r\nconst pnpNodeSettings: IPnpNodeSettings = {\r\n  /// ...\r\n};\r\n\r\nnew PnpNode(pnpNodeSettings).init().then(settings =\u003e {\r\n\r\n  // Here goes PnP JS Core code\r\n\r\n}).catch(console.log);\r\n```\r\n\r\n### Raw Fetch client usage\r\n\r\n```typescript\r\nimport { PnpNode } from 'sp-pnp-node';\r\n\r\ndeclare const global: any;\r\n\r\nnew PnpNode().init().then(settings =\u003e {\r\n\r\n  // Any raw RESP API requests with Fetch client\r\n  global.fetch(`${settings.siteUrl}/_api/web`, {\r\n    method: 'GET',\r\n    headers: {\r\n      accept: 'application/json;odata=minimalmetadata'\r\n    }\r\n  })\r\n    .then(response =\u003e response.json())\r\n    .then(console.log)\r\n    .catch(console.log);\r\n\r\n});\r\n\r\n```\r\n\r\n### PnP Node Settings options\r\n\r\n- siteUrl?: string; // Optional SPWeb url\r\n- authOptions?: IAuthOptions; `node-sp-auth` [credentials options](https://github.com/s-KaiNet/node-sp-auth)\r\n- config?: IAuthConf; `node-sp-auth-config` [options](https://github.com/koltyakov/node-sp-auth-config)\r\n  - configPath?: string; // Path to auth config .json | Default is './config/private.json'\r\n  - encryptPassword?: boolean; // Encrypts password to a machine-bind hash | Default is 'true'\r\n  - saveConfigOnDisk?: boolean; // Saves config .json to disk | Default is 'true'\r\n\r\nSettings can be left blank. Auth options in such a case will be asked by `node-sp-auth-config` [options](https://github.com/koltyakov/node-sp-auth-config) in a wizard like approach.\r\n\r\n### Settings scenarios\r\n\r\n- No initial settings (defaults): wizard approach, covers console applications cases with user interaction\r\n- With explicitly defined `authOptions`:\r\n  - external tools is in charge for preparing auth credentials in `node-sp-auth` format\r\n  - credentials should not be dumped on disc\r\n- Config file with prepopulated credentials: schedule, job automation, continues integration\r\n\r\n## Supported authentication scenarios\r\n\r\n- SharePoint On-Premise (2013, 2016):\r\n  - User credentials (NTLM)\r\n  - Form-based authentication (FBA)\r\n  - Add-In Only permissions\r\n  - ADFS user credentials\r\n\r\n- SharePoint Online:\r\n  - User credentials (SAML)\r\n  - Add-In Only permissions\r\n  - ADFS user credentials\r\n\r\n## Inspiration and references\r\n\r\nThis project was inspired by [Sergei Sergeev](https://github.com/s-KaiNet) and [Patrick Rodgers](https://github.com/patrick-rodgers). Main ideas were taken from [node-pnpjs-sample](https://github.com/s-KaiNet/node-pnpjs-sample) and [Using PnP JS Core and node-sp-auth](https://blogs.msdn.microsoft.com/patrickrodgers/2016/10/17/using-pnp-js-core-and-node-sp-auth/). The result project implements the same concepts with a goal of reusability and maintenance simplification.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fsp-pnp-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoltyakov%2Fsp-pnp-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fsp-pnp-node/lists"}