Getting Started: Install & Use

Within a TypeScript 2.0 project

NPM Install

This step will install the sp-pnp-js library into your project. The --save flag instructs npm to store a reference to the library in your package.json's dependencies section. You can read more on the npm install command.

npm install sp-pnp-js --save

Import to TypeScript file

Within a code file you can import the library from "sp-pnp-js". This brings in the default export from the library, which is the root object.

import pnp from "sp-pnp-js";

Begin using the API

You can read more on getting started using the library in our basic operations article in the developer's guide.

pnp.sp.web.get().then(w => { // ... });

Selectively Import

Starting with 1.0.5 you can selectively import parts of the library. This works for Site, Web, and many of the supporting classes. This also provides much better support for Webpack and similar bundlers.

import { Web } from "sp-pnp-js";
let w = new Web("{Absolute Web Path}");
w.get().then(w => { // ... });

You can also import the entire namespace to see what is available.

import * as spns from "sp-pnp-js";
let w = new spns.Web("{Absolute Web Path}");
w.get().then(w => { // ... });

let d = new spns.Dictionary<string>();
// ...

Using requirejs

Please see the sample visual studio project for an example using requirejs.

From a Content Editor WebPart.

1. Download pnp.js

2. Upload pnp.js to your site. In this example we will upload it to a library called "Style Library"

3. Add a new file called pnptest.html to the same library with the following content.

<script type="text/javascript" src="{PathToYourSite}/Style%20Library/pnp.js"></script>
<script type="text/javascript" src="{PathToYourSite}/Style%20Library/pnptest.js"></script>

<div id="main"></div>

4. Add a new file called pnptest.js to the same library with the following content:

$pnp.sp.web.select("Title").get()
.then(function(data){
   document.getElementById("main").innerText=data.Title;
})   
.catch(function(err){  
   document.getElementById("main").innerText=err;
});

5. Add a Content Editor WebPart to a page within the site

6. Set the url of the content editor webpart to "{PathToYourSite}/Style%20Library/pnptest.html"

7. Open the page in chrome, and the webpart will display the Title of your site.

Polyfill

The page will throw an error if you view it in Internet Explorer at this point because Internet Explorer does not support the fetch protocol or es6 promises, both of which are used by pnp.js. You also need to account for the fact that you are loading polyfills and must wait to execute your code until these are loaded. The easiest way to do this is to use a polyfill service such as polyfill.io. The second option would be to use requirejs, systemjs, or your module loader of choice.

Option 1 - Polyfill Service

To use this option you need to wrap the code in a function, here called "stuffisloaded". Then you need to add another script tag as shown below that will load what you need from the polyfill service. Note the parameter "callback" takes our function name.

<script>
// this function will be executed once the polyfill is loaded.
function stuffisloaded() {

  $pnp.sp.web.select("Title").get()
    .then(function(data){
      document.getElementById("main").innerText=data.Title;
  })   
  .catch(function(err){  
    document.getElementById("main").innerText=err;
  });
}
</script>
<!-- This script tag loads the required polyfills from the service -->
<script src="https://cdn.polyfill.io/v2/polyfill.min.js?callback=stuffisloaded&features=es6|always|gated,fetch|always|gated"></script>

Option 2 - Module Loader

If you are using a module loader you need to load the following two files as well. You can do this form a CDN or your style library.

1. Download the es6-promises polyfill from https://github.com/stefanpenner/es6-promise and upload it to your style library.

2. Download the fetch polyfill from https://github.com/github/fetch and upload it to your style library.

3. Update your module loader to set these files as dependencies before the pnp library is opened.

Now if you open the page in Internet Explorer, the webpart will display the site Title. One issue you still may see is that you get errors that certain libraries are undefined when you try to run your code. This is because your code is running before