repository·version-4·Indexed 21 days ago
https://github.com/pnp/pnpjsA fluent, type-safe JavaScript API for interacting with SharePoint and Microsoft Graph REST APIs. Compatible with SharePoint Framework (SPFx), Node.js, and general web applications. Includes guidance on ESM configuration for Azure Functions v4, certificate-based authentication in Node.js, and creating optimized custom bundles using Webpack or Rollup.
PnPjs is a fluent JavaScript API designed for consuming SharePoint and Microsoft Graph REST APIs in a type-safe manner. It is an open-source initiative that complements official Microsoft SDKs. It is compatible with various environments, including:
PnPjs is a collection of fluent, type-safe libraries designed to consume SharePoint, Microsoft Graph, and Office 365 REST APIs. It is compatible with SharePoint Framework (SPFx), Node.js, and general JavaScript projects.
All packages are published as a set and depend on their peers within the @pnp scope. Key packages include:
If you are migrating from version 2, refer to the transition guide in the repository.
@pnp/sp/site-users module provides methods to retrieve, create, update, and remove users within a SharePoint site collection. To use these methods, you must import the core @pnp/sp/webs module and the specific site users module (e.g., @pnp/sp/site-users/web).The @pnp/sp/social module allows you to manage and retrieve social interactions in SharePoint, such as following sites, people, documents, or tags.
Important Note: Most social methods require the context of a logged-in user and will not work with app-only permissions.
import { spfi } from "@pnp/sp";
import "@pnp/sp/social";
const sp = spfi(...);
// Access social features via sp.social@pnp/sp/column-defaults sub-module allows you to manage default column values for specific folders or an entire document library. This is useful for ensuring new items created within specific locations automatically inherit certain metadata.The @pnp/graph/compliance module provides access to Microsoft Graph compliance and privacy APIs, specifically for managing Subject Rights Requests (SRR) within Microsoft Purview. To use these features, you must import the compliance module alongside @pnp/graph to extend the graphfi instance.
import { graphfi } from "@pnp/graph";
import "@pnp/graph/compliance";
const graph = graphfi(...);IMessageRule and IMessageRules via Microsoft Graph. You can retrieve, add, update, and delete message rules for specific mail folders (such as the inbox) using the @pnp/graph package. Ensure you import @pnp/graph/users and @pnp/graph/mail to access the necessary mail folder and rule endpoints.When working with long file or folder paths in @pnp/sp, you may hit SharePoint URL length limits. You can bypass this by using Aliased Parameters. This feature allows you to replace long strings with short labels in the URL path, while the actual values are moved into the query string.
To create an alias, use the following pattern within your string:
!@{label name}::{value}
Rules for Aliases:
!) to trigger the replacement.::) between the label and the value.@ followed by a letter (e.g., @p1, @p2).@p1 and @p2 for different parameters in the same query).When the request is generated, the path segment is replaced by the label (e.g., @p1), and the original value is appended to the query string as a parameter (e.g., ?@p1='/your/long/path').
// Pattern: !@{label name}::{value}
// Example:
const query = sp.web.getFolderByServerRelativeUrl("!@p1::/sites/dev/Shared Documents/").files.select("Title").top(3);
// Resulting Request URL structure:
// _api/web/getFolderByServerRelativeUrl(@p1)/files?@p1='/sites/dev/Shared Documents/'&$select=Title&$top=3esm.ts resolver is used to ensure the built module output is loaded correctly. This is a custom resolver designed to handle the specific path resolution requirements of the built PnPjs modules in an ESM environment.The @pnp/graph/subscriptions module allows client applications to receive notifications about data changes in Microsoft Graph. This capability was introduced in version 1.2.9 of @pnp/graph.
Supported resources for subscriptions include:
PnPjs provides access to SharePoint web navigation through two main properties on the web.navigation object:
topNavigationBarquicklaunchBoth properties expose the same set of methods for managing navigation nodes. To use these, you must import @pnp/sp/webs and @pnp/sp/navigation.
import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/navigation";
const sp = spfi(...);
// Get references to the navigation objects
const top = await sp.web.navigation.topNavigationBar();
const quick = await sp.web.navigation.quicklaunch();Timelines created from other timelines (such as those generated by the sp and graph libraries) inherit all observers from their parent. Observers added to a parent apply to all children.
Important: Inheritance Breaking
Inheritance is broken as soon as you modify the set of observers on a child using subscription methods (like append, prepend, or replace).
Example of inheritance and breaking:
const sp = new spfi().using(...lots of behaviors);
// web inherits all observers from "sp"
const web = sp.web;
// Inheritance is now broken for 'web'.
// 'web' has its own observers and no longer tracks changes to 'sp'.
web.on.log(...);
// web2 is a fresh instance from 'sp', so it still inherits from 'sp'.
const web2 = sp.web;
// 'list' inherits from 'web' (including the 'log' observer added to 'web').
const list = web.lists.getById("");