Announcing PnPjs 2.0 JavaScript libraries
We are so excited to announce the release of PnPjs 2 JavaScript libraries. This release is the culmination of months of work to re-architect the PnPjs JavaScript library to support better modern development standards such as selective imports, to refactor inconsistencies in the implementation, and to update our testing and documentation to provide complete coverage of the entire code base. Although we’ve had some bumps along the way we are proud of the efforts and are excited to get the feedback from the community. As always, this work could not be done without the commitment from the community and we would like to thank all of those who contributed to getting version 2 out the door.
PnPjs is a collection of fluent libraries for consuming SharePoint, Graph, and Office 365 REST APIs in a type-safe way. You can use it within SharePoint Framework, Node.js, or any JavaScript project. This an open-source initiative and we encourage contributions and constructive feedback from the community.
Simplified Installation
First, lets start off with the improvements we made to installation. In the past the version 1 library had peer dependencies, which may be logically correct, but leads to confusion and a lot of extra work to install each of the required libraries. For version 2 we decided to change to a dependency model and so going forward you only need run:
npm install @pnp/sp --save
Selective Imports
Let’s be honest, we all tend to code first and optimize second. But when it came to optimize for version 1 you didn’t have much choice as the monolithic libraries offered no way to minimize them short of forking the repository and managing your own build. In version 2 we’ve implemented modern ES Modules that supports selective imports. This allows your bundling code to only import the bits of the PnPjs library that you’re using therefore reducing your bundle size significantly.
Of course, for those of you doing Node.js development (verses SPFx development) this becomes a bit of a problem when using older versions of Node.js that don’t support ES Modules, and so we’ve addressed that to with a set of modules built in CommonJS. You can read more in our updated article on working in Node.js.
Speaking of presets, we’ve created a set of presets for easier transition from version 1 or getting started quickly, if bundle size isn’t of critical importance for your project. And be sure to checkout our sample on creating in-project presets or create a custom bundle to support your projects.
Invokable Objects
Another enhancement from version 1 is the use of invokable objects. Previously you would need to finalize any command to PnPjs with .get() to execute the query. Going forward you will just be able to invoke the object itself: sp.web(). Not only does this make your code more readable but it also allows for default actions that are not get but instead might be post. For backward compatibility all .get() will continue to work.
Factory Functions & Interfaces
We’ve been hard at work refactoring all the exports. We’re no longer exporting the objects themselves but rather only exposing the factory function and interfaces. This allow us to decouple what developers use from our internal implementation. So, going forward instead of using the “new” keyword to create an instance of the object you will simply call the object and its type will be based on the interface not the object.
Extension Methods
One of the more exciting enhancements to the version 2 library is the introduction of extensions. The idea is that you would be able to override or add functionality to an object without altering the underlying classes. This can be extremely useful for debugging and testing but also adding some custom functionality to the library based on your personal requirements. Better yet, extensions work with ANY invokable object. Which means, you can customize the behavior of just about anything in the library.
Bundling
Because of the ability to do selective imports, a new benefit will be the ability for you to create your own custom PnPjs bundles. These bundles can have specific pieces of the PnPjs library you want to make available to your solution, or development team, but also allows you to bundle in any extension methods you created thereby building the perfect stand-alone library.
Well that’s a whole lot of great new functionality and we hope everyone is as excited as we are to try out the new library. We have a series of videos coming to help you get started, so be sure to check out our YouTube channel! Please take the time to review our transition guide as it’s really going to help you make the move from version 1 to version 2 a lot smoother. And if you have issues please submit an issue to our issues list so that someone in the community can assist you!
Also, if you feel like you’d like to contribute we’d be more than happy to have you, please see our contribution guide. You can also check out the “Sharing is Caring” initiative, where you can benefit from live hands-on guidance sessions on contributing to a variety of the Patterns and Practices projects. Additionally you can watch the video, “No Code Microsoft SharePoint PnP (Patterns and Practices) Contributions”, which provides an introduction to PnP contribution guidance principles.
“Sharing is caring!”
SharePoint Team, Microsoft – 29th of January 2020
Light
Dark