Template-based SharePoint Online provisioning in pure JavaScript/TypeScript. Apply a JSON template to a web — site fields, content types, site groups and permissions, lists (fields, views, folders, seeded rows, permissions), files, client-side pages, navigation, taxonomy and more — from the browser (SharePoint Framework) or from Node. Built on PnPjs and used by Prosjektportalen 365 for template-driven project setup.
npm install sp-js-provisioning @pnp/sp @pnp/core @pnp/logging @pnp/queryable --savePnPjs v4 (@pnp/sp 4.x) is a peer dependency: the IWeb
you pass to WebProvisioner must come from a v4 spfi(...), and it has to come from your
copy of @pnp/sp. PnPjs classes carry protected members, so two physically distinct copies of
the package are not assignable to each other and the build would fail on the WebProvisioner
constructor. Declaring the @pnp/* packages as peers lets the package manager enforce the
single instance. npm 7+ installs them for you; with legacy-peer-deps or Yarn 1, install them
explicitly as shown above.
import { LogLevel } from '@pnp/logging'
import { WebProvisioner, Schema } from 'sp-js-provisioning'
const template: Schema = {
WebSettings: {
WelcomePage: 'SitePages/Home.aspx'
},
Lists: [
{
Title: 'Checklist',
Description: '',
Template: 100,
ContentTypesEnabled: false,
AdditionalSettings: { EnableVersioning: true },
DataRows: {
KeyColumn: 'Title',
UpdateBehavior: 'Skip',
Rows: [{ Title: 'First checkpoint' }]
}
}
]
}
// `web` is a PnPjs IWeb for the site you are provisioning
const provisioner = new WebProvisioner(web).setup({
spfxContext: this.context, // in SPFx; in Node, pass a minimal page context (see debug/)
logging: { prefix: '(MySolution)', activeLogLevel: LogLevel.Info },
parameters: { MyParameter: 'value' } // resolved by {parameter:MyParameter}
})
await provisioner.applyTemplate(template, undefined, (handler) => {
console.log(`Running handler ${handler}`)
})applyTemplate(template, handlers?, progressCallback?) applies every section of the template
in a fixed order (see below). Pass an array of handler names as the second argument to run a
subset, e.g. ['SiteFields', 'ContentTypes', 'Lists'].
Running from Node works with any PnPjs v4 web, for example one set up with @pnp/nodejs (install
it yourself; it is not a dependency of this package). debug/ has a ready-made runner
that signs in with a Playwright session or an app certificate (debug/lib/auth.ts).
A template is a JSON object (TypeScript type Schema) where each top-level key is handled by
a dedicated handler, applied in this order:
| Order | Section | Provisions |
|---|---|---|
| 1 | Taxonomy |
Term groups, term sets and terms (ids, sort order, custom properties). UpdateExistingTerms fills missing custom properties onto existing terms |
| 2 | SiteFields |
Site columns from field XML: created when missing, updated in place on a re-apply (see Re-applying site columns) |
| 3 | ContentTypes |
Content types with fixed ids, field refs (by name) and field link order; only what differs is written (see Re-applying content types, term sets, files and the property bag) |
| 4 | Features |
Web feature activation and deactivation |
| 5 | Security |
Site groups (properties, owner, members) and role inheritance and role assignments on the web |
| 6 | Lists |
Lists and libraries: settings, content type bindings, list fields, field refs (site columns added to the list, by id), views, folder hierarchies, seeded rows (DataRows) and list permissions (Security) |
| 7 | Files |
Files from a source URL, byte for byte, with item properties and overwrite control |
| 8 | CustomActions |
User custom actions, including SPFx extension registrations |
| 9 | ComposedLook |
Theme (composed look) |
| 10 | ClientSidePages |
Modern pages with sections and web parts; a page the web has is kept, unless Overwrite or it was never published |
| 11 | PropertyBagEntries |
Property bag values: written when missing, overwritten only with Overwrite |
| 12 | Navigation |
Quick Launch and top navigation nodes, reconciled in place: the template owns each collection it names |
| 13 | WebSettings |
Web properties such as welcome page and master page, written when they differ from the web's |
| 14 | Hooks |
HTTP callbacks after provisioning |
schema.json is a JSON Schema for the template format — reference it from
your template files for editor validation and IntelliSense:
{
"$schema": "https://raw.githubusercontent.com/Puzzlepart/sp-js-provisioning/main/schema.json"
}See sample-schemas/ for a small end-to-end example and
docs/ARCHITECTURE.md for a deep dive into every handler,
the token system and the error model.
Lists can be seeded with items. Rows are upserted by KeyColumn: when a row with the same
key value exists, it is updated (UpdateBehavior: "Overwrite", the default) or left alone
("Skip"), so re-applying a template does not duplicate content. The key is matched with its
tokens replaced, as the item holds it. Field values are mapped by the field's type — lookup and
user values resolve to item/user ids, taxonomy values ({ termId, label }) write the hidden note
field, and string values (a URL's Url and Description too) get token replacement. A lookup or
user value that matches nothing is logged as an error and left out: a new item gets the values
that resolved, an existing one keeps what it holds in that column. SharePoint drops a term that is
not in the column's term set without a word: the taxonomy columns the rows wrote are read back
after the rows, and a term that is not stored is logged as an error naming the row and the value
(since 1.6.1).
A template can be applied again to a site that holds data (PP365 re-runs project setup and re-imports packages), and that changes no data (spec):
- A list field in
Fieldsthat exists is updated in place, never deleted: the template merged onto what SharePoint stores (what the template declares wins; what it leaves out keeps its value). A widening type change (TexttoNote,LookuptoLookupMulti,UsertoUserMulti) is applied; another type change is a warning and leaves the field as it is. A lookup pointed at another list, or a taxonomy field at another term set, follows the template on a list made in this setup; elsewhere it is a warning and keeps its target, because the stored values belong to it. A taxonomy field is merged as a taxonomy site column is: itsCustomization, hidden list,WebIdandShowFieldare SharePoint's and stay as stored, and its term set and term store are set as the field's own properties and read back, an error when SharePoint does not take them (since 1.6.1; aSchemaXmlupdate leaves them as they were). RemoveExistingViewsandRemoveExistingContentTypesact on lists made in this setup: created by this provisioner, across itsapplyTemplatecalls (a template and then its extensions). On a list that existed they do nothing. Neither removes a view the template names, a personal view, the default view or the view behind a page's list web part. (PnP Framework removes on every run.)- An existing list gets only the settings the template defines; one it leaves out keeps its value.
Since 1.6.1 only a setting that differs from the list's is written, and a field ref writes only
the
DisplayName,Required,HiddenandAdditionalPropertiesthat differ from the list field's: re-applying an unchanged template writes no list, field ref or view. - The views the template names are the template's: set when they differ from it (a
ViewQuerycompared as SharePoint stores it, without layout whitespace and with double quotes; view fields by their names cut to 32 characters, as SharePoint stores a projected lookup's). - List
Securitybreaks inheritance only on a list that still inherits; role assignments are added, never removed.
SiteFields follows the same rules as list fields (spec):
- A site column is identified by its internal name (
Name). One the web has is updated in place: the template merged onto what SharePoint stores (what the template declares wins; what it leaves out keeps its value, so an index, formatter or description an admin added survives), and nothing is written when that changes nothing. A widening type change (TexttoNote,LookuptoLookupMulti,UsertoUserMulti) is applied; another type change is a warning and leaves the column as it is. - A lookup pointed at another list, or a taxonomy column at another term set or term store, is a warning and keeps its target, unless the column was made in this setup. A target an earlier run stored as a literal token (or the empty GUID SharePoint stores for a literal term store id) follows the template, so the column heals.
- Site column changes do not reach the column's existing list copies: the engine never pushes them (SharePoint does not either, through the column or through a content type update).
- A column with the template column's id under another name is an error and is not created. On a subweb, a column a parent web has is neither created nor changed (a warning).
- A column SharePoint refuses is logged as an error, and the other columns and the handlers after
SiteFieldsstill run.
"Navigation": {
"QuickLaunch": [
{ "Title": "Hjem", "Url": "" },
{
"Title": "Prosjektinformasjon",
"Url": "SitePages/Prosjektinformasjon.aspx",
"Children": [{ "Title": "Fasesjekkliste", "Url": "Lists/Fasesjekkliste" }]
},
{ "Title": "Notatblokk", "Url": "#", "IgnoreExisting": true }
]
}The template owns each collection it names (QuickLaunch, TopNavigationBar); one it leaves
out is not touched. A run that succeeds leaves exactly the template's nodes in the collection, in
its order, children included (spec):
- A node whose title is already there at the same level (exact title, case included) is kept as it is: its id, its audiences and its URL. Nothing is written for it, so re-applying an unchanged template changes nothing.
- A missing node is added; a node the template does not declare is deleted, with its children
(SharePoint's default nodes, a node a site owner added). A kept node without
Childrenin the template loses the children it has. IgnoreExisting: truesets the template'sUrlon a node that exists, where it differs (%20or a space, a trailing slash, the case of a SharePoint path, and a web-relative or absolute form of the same URL count as the same). Without it an existing node keeps its stored URL, at every level: SharePoint changes it when the target page is renamed, and an owner may have. A title stored more than once gets the template's URL either way.Urlmay be server-relative, web-relative (SitePages/Home.aspx, resolved against the web), absolute, or#. It takes the URL tokens only ({site}is the site collection, also on a subweb);Titletakes none.- SharePoint refuses a node whose URL names no existing file or folder, or a page that has never
been published (a draft). The run then fails with
Navigation node '<Title>' (<Url>) was refused by SharePoint: ..., and the nodes and URLs the run had added or changed are undone, so both collections are left as they were. A page, file or list deleted since the last run takes its node with it, so the next run fails on that node. A template page a setup left unpublished when it stopped part way is published byClientSidePageson the next run (since 1.6.1), before Navigation runs. - SharePoint returns the titles of its own nodes (
Hjem,Dokumenter) in the language of the account that runs the template, so they match only for an account with the template's language; otherwise the node is added again and the stored one deleted.
"Security": {
"SiteGroups": [
{
"Title": "{sitename} Styringsgruppe",
"Description": "Styringsgruppen for {sitename}",
"Owner": "{associatedownergroupid}",
"AllowMembersEditMembership": false,
"OnlyAllowMembersViewMembership": false,
"Members": ["kari.nordmann@contoso.no"],
"ClearExistingMembers": false
}
],
"BreakRoleInheritance": false,
"RoleAssignments": [
{ "Principal": "{sitename} Styringsgruppe", "RoleDefinition": "Lese" }
]
}Site groups are matched by title, so re-applying a template updates an existing group instead
of creating a duplicate. Members are login names (UPN, email or claims, e.g. an Entra ID group
claim) and are ensured on the web before they are added. ClearExistingMembers removes members
that are not in Members, but only when every listed member could be added. Owner is resolved
like a role assignment principal (below) and may be the group itself; without it SharePoint
keeps the provisioning user as owner.
BreakRoleInheritance, CopyRoleAssignments, ClearSubscopes and RoleAssignments work as for
lists, but on the web. Inheritance is only broken when the web still inherits, so re-running a
template with ClearSubscopes does not wipe list permissions set since. The root web of a site
collection always has unique permissions and takes role assignments directly.
Security runs right before Lists, so list permissions can grant access to the groups it
creates. If you pass your own handlerSort to WebProvisioner, give Security a lower value
than Lists.
"Security": {
"BreakRoleInheritance": true,
"CopyRoleAssignments": false,
"ClearSubscopes": false,
"RoleAssignments": [
{ "Principal": "{associatedownergroupid}", "RoleDefinition": "Full kontroll" },
{ "Principal": "{associatedmembergroupid}", "RoleDefinition": "Lese" }
]
}A principal can be one of the associated-group tokens above, a principal id, a site group
name (including groups created by Security in the same template) or a user login name. Other
tokens such as {sitename} and {parameter:Name} are replaced first. Role definitions are
resolved by their name as it exists on the web (localized), with a fallback to the well-known
role types for the English names Full Control, Design, Edit, Contribute and Read.
Strings in field XML, data row values, file sources and client-side page properties can
reference values that are only known at provisioning time. Both {token} and {token:value}
forms are supported; unresolved or unknown tokens are left untouched. In site column XML, a known
token that cannot be resolved is also logged as an error naming the column and the token (the
column is still created with it as written). The URL tokens
{site} / {sitecollection} are the exception: they need a page context (SPFx, or a minimal
one in Node — see debug/) and resolve to null without one.
| Token | Resolves to |
|---|---|
{listid:List Title} |
Id of a list on the web (in SiteFields also one the same template creates) |
{listviewid:List Title|View Title} |
Id of a list view (not in SiteFields, see below) |
{webid} / {siteid} |
Id of the web being provisioned |
{sitename} |
Title of the web being provisioned |
{sitecollectionid} |
Id of the site collection |
{sitecollectiontermstoreid} / {termstoreid} |
Id of the default term store — enables managed metadata site columns from a template |
{parameter:Name} |
Value from IProvisioningConfig.parameters |
{site} / {sitecollection} |
Server-relative / absolute URL (in URLs) |
{wpgallery} / {themegallery} |
{sitecollection} + /_catalogs/wp / + /_catalogs/theme/15 (in URLs) |
{hosturl} |
Origin, https://contoso.sharepoint.com (in URLs; it ended in : before 1.5.0) |
{associatedownergroupid} / {associatedmembergroupid} / {associatedvisitorgroupid} |
Associated group (in Security principals and group owners) |
SiteFields runs before Lists, so {listid:} there resolves for lists that exist when the run
starts, and for a list the same template's Lists declares: WebProvisioner creates that list,
with its settings, before SiteFields (when both run and SiteFields comes first).
{listviewid:} does not resolve before Lists (for example in SiteFields), except for views an
earlier applyTemplate through the same provisioner processed.
Since 1.6.0 these four reach SharePoint through REST and CSOM over HTTP, never JSOM, and run in Node and under SPFx alike (spec):
- A content type the web has gets only what differs: a name, description or group, a field link it
lacks, a changed
RequiredorHidden, a changed order. An unchanged one is not written, so a re-run does not push it to every list and content type that inherits from it. A field ref whose site column is not on the web is logged as an error and the others are linked; a link the template does not name is never removed. - Taxonomy reads the term store once and writes a term set only when a term is missing, a term
lacks a custom property (
UpdateExistingTerms, never overwriting one) or the sort order differs. What the store has is not renamed or moved. - A file that already holds the source's bytes is not uploaded again;
Overwrite: falseleaves an existing file as it is; a file that fails is logged and the next is tried. Classic web parts (WebParts,RemoveExistingWebParts) are no longer supported: the file is provisioned and an error says so. - A property bag entry is written when its key is missing, and overwritten only with
Overwrite;Indexedadds the key to the indexed ones. A site that blocks custom script (modern sites do by default) refuses the write: one logged error, and the template goes on.
setup(config) accepts:
parameters— string map used by{parameter:...}tokens.spfxContext— the SPFx context; used for URL token resolution in the browser.logging—prefixandactiveLogLevelfor the built-in@pnp/loggingconsole listener.
Every request goes through the web you pass to WebProvisioner, with its pipeline: its sign-in and
its retries on throttling (PnPjs's SPFx behavior tries a 429, 503 or 504 again, honouring
Retry-After). The engine adds one retry of its own: a GET SharePoint answers 406 (it does so under
load, right after a page is published) is tried again up to three times. The web you pass is not
changed.
Errors are thrown as ProvisioningError, carrying the name of the handler that failed (handler)
and what it failed with (cause).
Sub-operations such as individual site columns, data rows, folders, site groups, group members
and role assignments log failures and continue, so one bad row does not abort the template.
git clone https://github.com/Puzzlepart/sp-js-provisioning.git
cd sp-js-provisioning
nvm use # Node version from .nvmrc
npm ci # .npmrc enables legacy peer dependency resolution
npm run build # tsc → lib/
npm test # node:test unit tests
npm run typecheck:tests # type-checks the tests together with srcnpm run provision runs a template against a real site from Node, signed in from .env
(.env.example) — see debug/README.md for setup. Changes are documented in
CHANGELOG.md.
Contributions are welcome. Please open an issue or submit a pull request on the GitHub repository.
MIT © Prosjektportalen. This repository continues the earlier
pnp-js-provisioning project.