Getting Started¶

This library is geared towards folks working with TypeScript but will work equally well for JavaScript projects. To get started you need to install the libraries you need via npm. Many of the packages have a peer dependency to other packages with the @pnp namespace meaning you may need to install more than one package. All packages are released together eliminating version confusion - all packages will depend on packages with the same version number.

If you need to support older browsers, SharePoint on premises servers, or older versions of the SharePoint Framework, please revert to version 2 of the library and see related documentation on polyfills for required functionality.

Minimal Requirements¶

- NodeJs: >= 18
- TypeScript: 4.x
- Node Modules Supported: ESM Only

Install¶

First you will need to install those libraries you want to use in your application. Here we will install the most frequently used packages. @pnp/sp to access the SharePoint REST API and @pnp/graph to access some of the Microsoft Graph API. This step applies to any environment or project.

npm install @pnp/sp @pnp/graph --save

Next we can import and use the functionality within our application. Below is a very simple example, please see the individual package documentation for more details and examples.

```ts
import { getRandomString } from "@pnp/core";

(function() {

    // get and log a random string
    console.log(getRandomString(20));

})()
```

Getting Started with SharePoint Framework¶

Quick References (v3 and v4 are the same for getting started)¶

More Details¶

The @pnp/sp and @pnp/graph libraries are designed to work seamlessly within SharePoint Framework projects with a small amount of upfront configuration. If you are running in 2016 or 2019 on-premises you will need to use version 2 of the library. If you are targeting SharePoint online you may need to take the additional steps outlined below based on the version of the SharePoint Framework you are targeting.

We've created two Getting Started samples. The first uses the more traditional React Component classes and can be found in the spfx-react-components sample project, utilizing SPFx 1.18.2 and PnPjs V4.

Although original created for V3, this 5 part video series is similar enough to v4 to give good direction for getting started with PnPjs:

Getting started with PnPjs 3.0: 5-part series

Also, again although this sample uses V3 of PnPjs it's a good getting started sample if you want to use PnPjs with React Hooks. This version can be found in react-pnp-js-hooks. This sample will help those struggling to establish context correctly while using the hooks conventions.

The SharePoint Framework supports different versions of NodeJS and TypeScript natively. Because of dependency updates we've made to PnPjs Version 4 is only compatible with NodeJS v18.x and therefore is not supported on SPFx version before 1.18.x.

SPFx Version 1.18.0 & later¶

No additional steps required

SPFx Version 1.15.0 => 1.17.4¶

Version 4 is not supported, you must use Version 3 because of V4 reliance requirement of NodeJS v18.x.

SPFx Version 1.12.1 => 1.14.0¶

Version 4 is not supported, you must use Version 3. In addition because as of SPFx 1.14.x release it still doesn't natively support TypeScript 4.x, this means that to use Version 3 of PnPjs you will need to take a few additional configuration steps to get them to work together.

Update the rush stack compiler to 4.2. This is covered in this great article by Elio, but the steps are listed below.
- Uninstall existing rush stack compiler (replace the ? with the version that is currently referenced in your package.json): npm uninstall @microsoft/rush-stack-compiler-3.?
- Install 4.2 version: npm i @microsoft/rush-stack-compiler-4.2
- Update tsconfig.json to extend the 4.2 config: "extends": "./node_modules/@microsoft/rush-stack-compiler-4.2/includes/tsconfig-web.json"

Replace the contents of the gulpfile.js with: >Note: The only change is the addition of the line to disable tslint.

```js
'use strict';

const build = require('@microsoft/sp-build-web');

build.addSuppression(`Warning - [sass] The local CSS class 'ms-Grid' is not camelCase and will not be type-safe.`);

var getTasks = build.rig.getTasks;
build.rig.getTasks = function () {
    var result = getTasks.call(build.rig);

    result.set('serve', result.get('serve-deprecated'));

    return result;
};

// ********* ADDED *******
// disable tslint
build.tslintCmd.enabled = false;
// ********* ADDED *******

build.initialize(require('gulp'));
```

SPFx Version 1.11.0 & earlier¶

At this time there is no documented method to use version 3.x with SPFx versions earlier than 1.12.1. We recommend that you fall back to using version 2 of the library or update your SPFx version.

Imports and usage¶

Because SharePoint Framework provides a local context to each component we need to set that context within the library. This allows us to determine request urls as well as use the SPFx HttpGraphClient within @pnp/graph. To establish context within the library you will need to use the SharePoint or Graph Factory Interface depending on which set of APIs you want to utilize. For SharePoint you will use the spfi interface and for the Microsoft Graph you will use the graphfi interface whic are both in the main export of the corresponding package. Examples of both methods are shown below.

Depending on how you architect your solution establishing context is done where you want to make calls to the API. The examples demonstrate doing so in the onInit method as a local variable but this could also be done to a private variable or passed into a service.

Note if you are going to use both the @pnp/sp and @pnp/graph packages in SPFx you will need to alias the SPFx behavior import, please see the section below for more details.

Using @pnp/sp `spfi` factory interface in SPFx¶

```TypeScript
import { spfi, SPFx } from "@pnp/sp";

// ...

protected async onInit(): Promise<void> {

    await super.onInit();
    const sp = spfi().using(SPFx(this.context));

}

// ...

```

Using @pnp/graph `graphfi` factory interface in SPFx¶

```TypeScript
import { graphfi, SPFx } from "@pnp/graph";

// ...

protected async onInit(): Promise<void> {

    await super.onInit();
    const graph = graphfi().using(SPFx(this.context));

}

// ...

```

Using both @pnp/sp and @pnp/graph in SPFx¶

```TypeScript

import { spfi, SPFx as spSPFx } from "@pnp/sp";
import { graphfi, SPFx as graphSPFx} from "@pnp/graph";

// ...

protected async onInit(): Promise<void> {

    await super.onInit();
    const sp = spfi().using(spSPFx(this.context));
    const graph = graphfi().using(graphSPFx(this.context));

}

// ...

```

Project Config/Services Setup¶

Please see the documentation on setting up a config file or a services for more information about establishing and instance of the spfi or graphfi interfaces that can be reused. It is a common mistake with users of V3 that they try and create the interface in event handlers which causes issues.

Getting started with NodeJS¶

Due to the way in which Node resolves ESM modules when you use selective imports in node you must include the index.js part of the path. Meaning an import like import "@pnp/sp/webs" in examples must be import "@pnp/sp/webs/index.js". Root level imports such as import { spfi } from "@pnp/sp" remain correct. The samples in this section demonstrate this for their selective imports.

Importing NodeJS support¶

Note that the NodeJS integration relies on code in the module @pnp/nodejs. It is therefore required that you import this near the beginning of your program, using simply

```js
import "@pnp/nodejs";
```

Azure Functions - NodeJS usage¶

As of now, by default the template for new Azure Functions uses CommonJS modules. Although you can use ESM in CommonJS projects you need to do the imports asynchronously. This works however it has the disadvantage of not working with intellisense which can be limiting.

```ts
const { MyClass } = await import("./myClass.js");

MyClass.init();
```

We recommend switching the project to ESModules by making the following changes:

An Azure Function sample is available.

Modification for `package.json`¶

```json
{
//...
"type": "module",
//...
}
```

Sample `tsconfig.json`¶

```json
{
"compilerOptions": {
    "module": "ESNext",
    "target": "ESNext",
    "outDir": "dist",
    "rootDir": ".",
    "sourceMap": true,
    "strict": false,
    "moduleResolution": "Node",
    "allowSyntheticDefaultImports": true,
    "typeRoots": [
    "./node_modules/@types"
    ],
}
}
```

Authentication¶

To call the SharePoint APIs via MSAL you are required to use certificate authentication with your application. Fully covering certificates is outside the scope of these docs, but the following commands were used with openssl to create testing certs for the sample code below.

```cmd
mkdir \temp
cd \temp
openssl req -x509 -newkey rsa:2048 -keyout keytmp.pem -out cert.pem -days 365 -passout pass:HereIsMySuperPass -subj '/C=US/ST=Washington/L=Seattle'
openssl rsa -in keytmp.pem -out key.pem -passin pass:HereIsMySuperPass
```

Using the above code you end up with three files, "cert.pem", "key.pem", and "keytmp.pem". The "cert.pem" file is uploaded to your AAD application registration. The "key.pem" is read as the private key for the configuration.

Using @pnp/sp `spfi` factory interface in NodeJS¶

Version 3 of this library only supports ESModules. If you still require commonjs modules please check out version 2.

The first step is to install the packages that will be needed. You can read more about what each package does starting on the packages page.

```cmd
npm i @pnp/sp @pnp/nodejs
```

Once these are installed you need to import them into your project, to communicate with SharePoint from node we'll need the following imports:

```TypeScript

import { SPDefault } from "@pnp/nodejs";
import "@pnp/sp/webs/index.js";
import { readFileSync } from 'fs';
import { Configuration } from "@azure/msal-node";

function() {
    // configure your node options (only once in your application)
    const buffer = readFileSync("c:/temp/key.pem");

    const config: Configuration = {
        auth: {
            authority: "https://login.microsoftonline.com/{tenant id or common}/",
            clientId: "{application (client) i}",
            clientCertificate: {
            thumbprint: "{certificate thumbprint, displayed in AAD}",
            privateKey: buffer.toString(),
            },
        },
    };

    const sp = spfi().using(SPDefault({
        baseUrl: 'https://{my tenant}.sharepoint.com/sites/dev/',
        msal: {
            config: config,
            scopes: [ 'https://{my tenant}.sharepoint.com/.default' ]
        }
    }));

    // make a call to SharePoint and log it in the console
    const w = await sp.web.select("Title", "Description")();
    console.log(JSON.stringify(w, null, 4));
}();
```

Using @pnp/graph `graphfi` factory interface in NodeJS¶

Similar to the above you can also make calls to the Microsoft Graph API from node using the libraries. Again we start with installing the required resources. You can see ./debug/launch/graph.ts for a live example.

```cmd
npm i @pnp/graph @pnp/nodejs
```

Now we need to import what we'll need to call graph

```TypeScript
import { graphfi } from "@pnp/graph";
import { GraphDefault } from "@pnp/nodejs";
import "@pnp/graph/users/index.js";

function() {
    const graph = graphfi().using(GraphDefault({
    baseUrl: 'https://graph.microsoft.com',
    msal: {
        config: config,
        scopes: [ 'https://graph.microsoft.com/.default' ]
    }
    }));
    // make a call to Graph and get all the groups
    const userInfo = await graph.users.top(1)();
    console.log(JSON.stringify(userInfo, null, 4));
}();
```

Node project using TypeScript producing commonjs modules¶

For TypeScript projects which output commonjs but need to import esm modules you will need to take a few additional steps to use the pnp esm modules. This is true of any esm module with a project structured in this way, not specific to PnP's implementation. It is very possible there are other configurations that make this work, but these steps worked in our testing. We have also provided a basic sample showing this setup.

You must install TypeScript @next or you will get errors using node12 module resolution. This may change but is the current behavior when we did our testing.

npm install -D typescript@next

The tsconfig file for your project should have the "module": "CommonJS" and "moduleResolution": "node12", settings in addition to whatever else you need.

tsconfig.json¶

```JSON
{
    "compilerOptions": {
        "module": "CommonJS",
        "moduleResolution": "node12"
}
```

You must then import the esm dependencies using the async import pattern. This works as expected with our selective imports, and vscode will pick up the intellisense as expected.

index.ts¶

```TypeScript
import { settings } from "./settings.js";

// this is a simple example as async await is not supported with commonjs output
// at the root.
setTimeout(async () => {

    const { spfi } = await import("@pnp/sp");
    const { SPDefault } = await import("@pnp/nodejs");
    await import("@pnp/sp/webs/index.js");

    const sp = spfi().using(SPDefault({
        baseUrl: settings.testing.sp.url,
        msal: {
            config: settings.testing.sp.msal.init,
            scopes: settings.testing.sp.msal.scopes
        }
    }));

    // make a call to SharePoint and log it in the console
    const w = await sp.web.select("Title", "Description")();
    console.log(JSON.stringify(w, null, 4));

}, 0);
```

Finally, when launching node you need to include the `` flag with a setting of 'node'.

node --experimental-specifier-resolution=node dist/index.js

Read more in the releated TypeScript Issue, TS pull request Adding the functionality, and the TS Docs.

Single Page Application Context¶

In some cases you may be working in a client-side application that doesn't have context to the SharePoint site. In that case you will need to utilize the MSAL Client, you can get the details on creating that connection in this article.

Selective Imports¶

This library has a lot of functionality and you may not need all of it. For that reason, we support selective imports which allow you to only import the parts of the sp or graph library you need, which reduces your overall solution bundle size - and enables treeshaking.

You can read more about selective imports.

Error Handling¶

This article describes the most common types of errors generated by the library. It provides context on the error object, and ways to handle the errors. As always you should tailor your error handling to what your application needs. These are ideas that can be applied to many different patterns.

Extending the Library¶

Because of the way the fluent library is designed by definition it's extendible. That means that if you want to build your own custom functions that extend the features of the library this can be done fairly simply. To get more information about creating your own custom extensions check out extending the library article.

Connect to a different Web¶

The new factory function allows you to create a connection to a different web maintaining the same setup as your existing interface. You have two options, either to 'AssignFrom' or 'CopyFrom' the base timeline's observers. The below example utilizes 'AssignFrom' but the method would be the same regadless of which route you choose. For more information on these behaviors see Core/Behaviors.

```TypeScript
import { spfi, SPFx } from "@pnp/sp";
import { AssignFrom } from "@pnp/core";
import "@pnp/sp/webs";

//Connection to the current context's Web
const sp = spfi(...);

// Option 1: Create a new instance of Queryable
const spWebB = spfi({Other Web URL}).using(SPFx(this.context));

// Option 2: Copy/Assign a new instance of Queryable using the existing
const spWebB = spfi({Other Web URL}).using(AssignFrom(sp.web));

// Option 3: Create a new instance of Queryable using other credentials?
const spWebB = spfi({Other Web URL}).using(SPFx(this.context));

// Option 4: Create new Web instance by using copying SPQuerable and new pointing to new web url (e.g. https://contoso.sharepoint.com/sites/Web2)
const web = Web([sp.web, {Other Web URL}]);
```

Multi-Geo / Cross tenant calls in SharePoint Framework (SPFx)¶

If you are working in a multi-geo tenant or trying to work across tenants (essentially the same thing) then the normal configuration in SPFx will not work. To connect cross tenants in the browser you will need to us the @pnp/msaljsclient to make the connection to the other tenant or geo.

Next Steps¶

For more complicated authentication scenarios please review the article describing all of the available authentication methods.