Managing SharePoint Site Designs and Site Scripts using PnP PowerShell

Site Designs and Site Scripts in SharePoint Online allow administrators to automate site provisioning by applying custom configurations to newly created sites. These configurations can include theme settings, lists, libraries, permissions, branding, and more.

Using PnP PowerShell, you can efficiently create, apply, update, and remove Site Designs and Site Scripts without using the SharePoint Admin UI.

---

Prerequisites

Before using PnP PowerShell for Site Designs and Site Scripts, ensure that:

You have SharePoint Admin or Global Admin permissions.
You have PnP PowerShell installed.
You are connected to SharePoint Online.

---

Step 1: Install and Import PnP PowerShell

If you haven’t installed PnP PowerShell yet, install it using:

Install-Module -Name PnP.PowerShell -Scope CurrentUser -AllowClobber -Force

Then, import the module:

Import-Module PnP.PowerShell

---

Step 2: Connect to SharePoint Online

To manage Site Designs and Site Scripts, connect to your SharePoint Admin Center:

Connect-PnPOnline -Url "https://yourtenant-admin.sharepoint.com" -Interactive

🔹 Replace "yourtenant" with your actual tenant name.

For app-based authentication:

Connect-PnPOnline -Url "https://yourtenant-admin.sharepoint.com" -ClientId "Your-App-Client-ID" -Tenant "yourtenant.onmicrosoft.com" -CertificatePath "Path\To\Certificate.pfx"

---

Step 3: List Existing Site Scripts

To check available Site Scripts in your tenant:

Get-PnPSiteScript

This will display all Site Scripts with their IDs, Titles, and Descriptions.

---

Step 4: Create a Site Script

A Site Script is a JSON-based file that defines site customizations. Here’s an example script that:
✔ Creates a document library
✔ Adds a site theme
✔ Applies a site logo

1. Define the JSON for the Site Script

Save the following JSON content in a file named SiteScript.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
  "actions": [
    {
      "verb": "createSPList",
      "listName": "Project Documents",
      "templateType": 101,
      "subactions": [
        {
          "verb": "setTitle",
          "title": "Project Docs"
        }
      ]
    },
    {
      "verb": "applyTheme",
      "themeName": "Company Theme"
    },
    {
      "verb": "setSiteLogo",
      "url": "https://yourtenant.sharepoint.com/SiteAssets/logo.png"
    }
  ],
  "version": 1
}

2. Add the Site Script using PnP PowerShell

Run the following command to create the Site Script in SharePoint Online:

$siteScriptJson = Get-Content "C:\Path\To\SiteScript.json" -Raw  
$siteScript = Add-PnPSiteScript -Title "Project Management Script" -Content $siteScriptJson  

The script is now added to SharePoint and ready to be used in a Site Design.

---

Step 5: List All Site Designs

To see the existing Site Designs:

Get-PnPSiteDesign

This lists all available Site Designs and their corresponding Site Scripts.

---

Step 6: Create a Site Design

A Site Design groups one or more Site Scripts together and applies them to a specific site template (Team Site, Communication Site, etc.).

$siteDesign = Add-PnPSiteDesign -Title "Project Site Design" -Description "A custom design for project sites" -SiteScriptIds $siteScript.Id -WebTemplate "64" -IsDefault $false

🔹 Web Template “64” → Team Site
🔹 Web Template “68” → Communication Site

This Site Design can now be applied when creating new sites.

---

Step 7: Apply a Site Design to an Existing Site

To manually apply a Site Design to an existing site:

Invoke-PnPSiteDesign -Identity $siteDesign.Id -WebUrl "https://yourtenant.sharepoint.com/sites/YourSite"

The Site Design configurations will be applied immediately.

---

Step 8: Remove a Site Design or Site Script

1. Remove a Site Design

Remove-PnPSiteDesign -Identity $siteDesign.Id -Confirm:$false

2. Remove a Site Script

Remove-PnPSiteScript -Identity $siteScript.Id -Confirm:$false

This permanently deletes the Site Design or Site Script.

---

Step 9: Update a Site Script or Site Design

1. Update a Site Script

Modify your SiteScript.json file and re-upload it:

Set-PnPSiteScript -Identity $siteScript.Id -Title "Updated Project Management Script" -Content (Get-Content "C:\Path\To\UpdatedSiteScript.json" -Raw)

2. Update a Site Design

To update the title or description of an existing Site Design:

Set-PnPSiteDesign -Identity $siteDesign.Id -Title "Updated Project Site Design" -Description "Updated description"

The Site Design and Site Script will be updated accordingly.

---

Step 10: Disconnect the PowerShell Session

To end the session securely:

powershellCopyEditDisconnect-PnPOnline

✅ This prevents unauthorized access.

---

Common Errors & Troubleshooting

Error	Cause	Solution
No Site Scripts found	No scripts exist	Create a Site Script using Add-PnPSiteScript
The specified Site Script does not exist	Wrong ID	Verify the Site Script ID using Get-PnPSiteScript
Access Denied	Insufficient permissions	Ensure you have SharePoint Admin or Global Admin access
Failed to apply Site Design	Invalid Web Template	Use correct Web Template IDs (64 for Team Sites, 68 for Communication Sites)
Cannot connect to SharePoint Online	Authentication issues	Use -Interactive login or App-based authentication