{"id":21655952,"url":"https://github.com/koltyakov/sp-jsom-node","last_synced_at":"2025-04-11T21:32:57.825Z","repository":{"id":21558086,"uuid":"92929051","full_name":"koltyakov/sp-jsom-node","owner":"koltyakov","description":"🚴 SharePoint JavaScript Object Model for Node.js","archived":false,"fork":false,"pushed_at":"2023-03-04T02:43:15.000Z","size":6037,"stargazers_count":21,"open_issues_count":4,"forks_count":4,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-14T23:12:09.749Z","etag":null,"topics":["api","jsom","nodejs","sharepoint","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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-31T09:25:55.000Z","updated_at":"2024-06-18T21:16:08.555Z","dependencies_parsed_at":"2024-06-18T21:16:00.297Z","dependency_job_id":"833918f5-7e1b-4851-b914-26ca74c0f462","html_url":"https://github.com/koltyakov/sp-jsom-node","commit_stats":{"total_commits":163,"total_committers":4,"mean_commits":40.75,"dds":0.6012269938650308,"last_synced_commit":"20d5db5d1d56906e1283565cdf067f9fbcb4e2bd"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-jsom-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-jsom-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-jsom-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fsp-jsom-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koltyakov","download_url":"https://codeload.github.com/koltyakov/sp-jsom-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482920,"owners_count":21111400,"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","jsom","nodejs","sharepoint","typescript"],"created_at":"2024-11-25T08:37:54.323Z","updated_at":"2025-04-11T21:32:57.799Z","avatar_url":"https://github.com/koltyakov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sp-jsom-node - SharePoint JavaScript Object Model for Node.js\r\n\r\n[![NPM](https://nodei.co/npm/sp-jsom-node.png?mini=true\u0026downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/sp-jsom-node/)\r\n\r\n[![npm version](https://badge.fury.io/js/sp-jsom-node.svg)](https://badge.fury.io/js/sp-jsom-node)\r\n[![Downloads](https://img.shields.io/npm/dm/sp-jsom-node.svg)](https://www.npmjs.com/package/sp-jsom-node)\r\n[![Build Status](https://koltyakov.visualstudio.com/SPNode/_apis/build/status/sp-jsom-node?branchName=master)](https://koltyakov.visualstudio.com/SPNode/_build/latest?definitionId=8\u0026branchName=master)\r\n[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/sharepoint-node/Lobby)\r\n\r\n`sp-jsom-node` provides a feasibility of using JSOM (CSOM, SharePoint Client Object Model) in Node.js.\r\n\r\n`sp-jsom-node` patches global variables and request client which let's `JSOM` used to behave as if it were in it's usual environment - a browser's SharePoint page.\r\n\r\n## Supported SharePoint versions\r\n\r\n- SharePoint Online, Project Online\r\n- SharePoint 2019, 2016, Project Server\r\n- SharePoint 2013\r\n- SharePoint 2010 [not officially supported]\r\n\r\n## APIs list\r\n\r\n- `core` - core JSOM module (loaded by default at first place)\r\n- `search` - sp.search.js\r\n- `publishing` - [sp.publishing.js](https://msdn.microsoft.com/en-us/library/office/jj607192.aspx)\r\n- `taxonomy` - [sp.taxonomy.js](https://msdn.microsoft.com/en-us/library/office/jj857114.aspx)\r\n- `userprofiles` - [sp.userprofiles.js](https://msdn.microsoft.com/en-us/library/office/jj642927.aspx)\r\n- `documentmanagement` - [sp.documentmanagement.js](https://msdn.microsoft.com/en-us/library/office/jj607384.aspx)\r\n- `workmanagement` - [sp.workmanagement.js](https://msdn.microsoft.com/en-us/library/office/jj607384.aspx)\r\n- `policy` - sp.policy.js\r\n- `project` - [PS.js](https://msdn.microsoft.com/en-us/library/office/jj669820.aspx) (Project Server API)\r\n\r\n## Supported authentication scenarios\r\n\r\n- SharePoint On-Premise (2019, 2016, 2013):\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## Installation\r\n\r\n```bash\r\nnpm install sp-jsom-node --save\r\n```\r\n\r\n## Usage examples\r\n\r\n![JsomNode Demo](./docs/imgs/JsomNode.demo.gif)\r\n\r\n### Minimal setup (TypeScript)\r\n\r\n```typescript\r\nimport { JsomNode, IConfigSettings } from 'sp-jsom-node';\r\n\r\nexport const setting: IConfigSettings = {\r\n  configPath: './config/private.json'\r\n}; // Optional setting, by default ./config/private.json is used\r\n\r\nnew JsomNode().wizard(setting).then((siteUrl) =\u003e {\r\n\r\n  /// ... \u003c\u003c\u003c JSOM can be used here\r\n\r\n  const ctx = new SP.ClientContext(siteUrl);\r\n\r\n}).catch(console.log);\r\n```\r\n\r\nFirst wizard run propmts for SharePoint site url and credentials strategy parameters.\r\n\r\n### Minimal setup (JavaScript)\r\n\r\n```typescript\r\nconst JsomNode = require('sp-jsom-node').JsomNode;\r\n\r\nnew JsomNode().wizard().then((siteUrl) =\u003e {\r\n\r\n  /// ... \u003c\u003c\u003c JSOM can be used here\r\n\r\n  const ctx = new SP.ClientContext(siteUrl);\r\n\r\n}).catch(console.log);\r\n```\r\n\r\n### Initiation with parameters\r\n\r\n```typescript\r\nimport { JsomNode, IJsomNodeContext } from 'sp-jsom-node';\r\n\r\nconst authOptions: any = require('./config/private.json');\r\nconst authContext: IJsomNodeContext = {\r\n  siteUrl: authOptions.siteUrl,\r\n  authOptions\r\n};\r\n\r\nconst ctx = new JsomNode().init(authContext).getContext();\r\n\r\n/// ... \u003c\u003c\u003c JSOM can be used here\r\n\r\n// const ctx = SP.ClientContext.get_current(); // works with single environment\r\nconst oWeb = ctx.get_web();\r\nconst oLists = oWeb.get_lists();\r\n\r\nconst listCreationInfo = new SP.ListCreationInformation();\r\nlistCreationInfo.set_title('New Lists');\r\nlistCreationInfo.set_templateType(100);\r\nconst oList = oLists.add(listCreationInfo);\r\n\r\nctx.load(oList);\r\nctx.executeQueryAsync(() =\u003e {\r\n  console.log(oList);\r\n}, (sender, args) =\u003e {\r\n  console.log(args.get_message());\r\n});\r\n```\r\n\r\n### Async/Await usage\r\n\r\nClient context runtime is extended with `executeQueryPromise` - promisified version of `executeQueryAsync`. Which allows coding with async/await in a \"synchronous\" handy style, having elegant and easily maintainable code.\r\n\r\n```typescript\r\nimport { JsomNode, IJsomNodeContext } from 'sp-jsom-node';\r\n\r\nconst authOptions: any = require('./config/private.json');\r\nconst authContext: IJsomNodeContext = {\r\n  siteUrl: authOptions.siteUrl,\r\n  authOptions\r\n};\r\n\r\n(async () =\u003e {\r\n\r\n  const clientContex = new JsomNode().init(authOptions).getContext();\r\n  // const clientContex = SP.ClientContext.get_current();\r\n  const oListsCollection = clientContext.get_web().get_lists();\r\n\r\n  clientContext.load(oListsCollection, 'Include(Title)');\r\n  await clientContext.executeQueryPromise(); // Using JSOM extension\r\n\r\n  const listsTitlesArr = oListsCollection.get_data()\r\n    .map((l) =\u003e l.get_title());\r\n\r\n  console.log('Lists', listsTitlesArr);\r\n\r\n})()\r\n  .catch(console.error);\r\n```\r\n\r\n### Modules\r\n\r\nBy default, only core modules are loaded.\r\nAdditional CSOM features can be requested in `modules` setting.\r\n\r\n[Modules list](#apis-list).\r\n\r\n```typescript\r\nimport { JsomNode, IJsomNodeSettings } from 'sp-jsom-node';\r\n\r\n// ...authOptions\r\n\r\nconst settings: any = require('./config/private.json');\r\nconst jsomSettings: IJsomNodeSettings = {\r\n  modules: [ 'taxonomy', 'userprofiles' ],\r\n  envCode: '2013' // 'spo' is default\r\n};\r\n\r\nnew JsomNode(jsomSettings).init(authOptions);\r\n\r\n/// ... \u003c\u003c\u003c JSOM can be used here\r\n```\r\n\r\n### Project server (PM.js)\r\n\r\n```typescript\r\nimport { JsomNode, IJsomNodeSettings } from 'sp-jsom-node';\r\n\r\n// ...authOptions\r\n\r\nconst settings: any = require('./config/private.json');\r\nconst jsomSettings: IJsomNodeSettings = {\r\n  modules: [ 'project' ]\r\n};\r\n\r\nnew JsomNode(jsomNodeOptions).init(authOptions);\r\n\r\n(async () =\u003e {\r\n\r\n  // API Reference - https://msdn.microsoft.com/en-us/library/office/jj669820.aspx\r\n  const projCtx = PS.ProjectContext.get_current();\r\n  const projects = projCtx.get_projects();\r\n  projCtx.load(projects, 'Include(Name, Id)');\r\n  await projCtx.executeQueryPromise();\r\n\r\n  console.log(projects.get_data().map(p =\u003e p.get_name()));\r\n\r\n})()\r\n  .catch(console.error);\r\n```\r\n\r\n#### JSOM Node Settings options\r\n\r\n- `modules`?: JsomModules[]; // On demand modules load | Default is ['core']\r\n- `envCode`?: 'spo' | '2019' | '2016' | '2013'; // Loads different version of JSOM javascripts | Default is 'spo'\r\n\r\n#### Synchronous initiation `.init(context: IJsomNodeContext)`\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\r\n#### Async/wizard initiation `.wizard(config?: IConfigSettings)`\r\n\r\n`node-sp-auth-config` [options](https://github.com/koltyakov/node-sp-auth-config)\r\n\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- ... [see more](https://github.com/koltyakov/node-sp-auth-config)\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## Integration tests\r\n\r\n```bash\r\nnpm run test\r\n```\r\n\r\n![Integration tests](./docs/imgs/mocha.jpg)\r\n\r\n## Bundling scripts\r\n\r\nWhen creating automation scripts for production environment, e.g. Azure Job or Function or embedded application like Electron, it can be important to bundle and minify sources with positive performant effect as a result.\r\nCheck [example](https://github.com/koltyakov/sp-jsom-node/tree/master/examples/basic) with bundling.\r\n\r\n## Inspiration and references\r\n\r\nThis project was mostly inspired by [Vadim Gremyachev](https://github.com/vgrem)'s project - [CSOMNode](https://github.com/vgrem/CSOMNode), but implements JSOM in node in a bit different way, in TypeScript and supports different auth scenarious implemented in [node-sp-auth](https://github.com/s-KaiNet/node-sp-auth) by [Sergei Sergeev](https://github.com/s-KaiNet).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fsp-jsom-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoltyakov%2Fsp-jsom-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fsp-jsom-node/lists"}