Managing Site Design JSON Templates using PnP PowerShell

SharePoint Site Designs allow administrators to apply custom configurations to sites automatically. These designs define themes, navigation, lists, libraries, content types, and other site settings. With PnP PowerShell, you can efficiently create, manage, and apply Site Design JSON templates to automate SharePoint site provisioning.

In this guide, we will cover:
Understanding Site Designs & Site Scripts
Creating a JSON Template for a Site Script
Adding a Site Script using PnP PowerShell
Creating & Applying a Site Design
Modifying & Removing Site Designs
Automating Site Design Deployment

Prerequisites

Before working with PnP PowerShell for managing Site Design JSON templates:

Install PnP PowerShell (if not installed)

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

Connect to SharePoint Online

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

Ensure You Have:

SharePoint Administrator or Global Admin permissions
Modern SharePoint sites enabled

Step 1: Understanding SharePoint Site Designs & Site Scripts

Site Scripts: JSON-based instructions defining site configurations (e.g., create lists, apply themes).
Site Designs: Higher-level templates that combine multiple Site Scripts into a reusable package.
Application Scope:

Applied to new site provisioning
Can be manually applied to existing sites

Step 2: Create a JSON Site Script Template

Create a JSON file (SiteScript.json) defining your site configuration.

Example JSON for Site Script

{
  "$schema": "schema.json",
  "actions": [
    {
      "verb": "createSPList",
      "listName": "Project Documents",
      "templateType": 101,
      "subactions": [
        {
          "verb": "addSPField",
          "fieldType": "Text",
          "displayName": "Project Name",
          "internalName": "ProjectName",
          "isRequired": true
        },
        {
          "verb": "addSPField",
          "fieldType": "DateTime",
          "displayName": "Start Date",
          "internalName": "StartDate",
          "isRequired": false
        }
      ]
    },
    {
      "verb": "applyTheme",
      "themeName": "Contoso-Blue"
    },
    {
      "verb": "setSiteLogo",
      "url": "https://yourtenant.sharepoint.com/SiteAssets/Logo.png"
    }
  ],
  "bindata": {},
  "version": 1
}

This script does the following:
Creates a Document Library named "Project Documents"
Adds “Project Name” and “Start Date” columns
Applies the “Contoso-Blue” theme
Sets a custom site logo

Step 3: Add the Site Script Using PnP PowerShell

Once the JSON file is created, use the following command to add the Site Script:

$siteScriptJSON = Get-Content "C:\Path\To\SiteScript.json" -Raw
$siteScript = Add-PnPSiteScript -Title "Project Site Script" -Description "Creates a project document library and applies theme" -Content $siteScriptJSON

Stores the Site Script in SharePoint for future use.

Step 4: Create a Site Design & Assign Site Scripts

Now, create a Site Design that uses the Site Script:

$siteDesign = Add-PnPSiteDesign -Title "Project Site Design" -WebTemplate "64" -SiteScripts $siteScript.Id -Description "Standard Project Site Design"

Parameters Explained:
Title: "Project Site Design"
WebTemplate: "64" (for Team Sites; use "68" for Communication Sites)
SiteScripts: Assigns the Site Script created earlier
Description: "Standard Project Site Design"

Step 5: Retrieve Existing Site Designs & Site Scripts

List All Site Scripts

Get-PnPSiteScript

List All Site Designs

Get-PnPSiteDesign

This helps verify the registered Site Scripts & Designs.

Step 6: Apply a Site Design to an Existing Site

Manually apply a Site Design to a specific SharePoint site:

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

This applies "Project Site Design" to the existing "ProjectSite".

Step 7: Modify an Existing Site Design

If changes are needed:

1️⃣ Retrieve the Site Design ID

$siteDesign = Get-PnPSiteDesign | Where-Object { $_.Title -eq "Project Site Design" }

2️⃣ Modify Site Design (e.g., add another Site Script)

Set-PnPSiteDesign -Identity $siteDesign.Id -Title "Updated Project Site Design" -SiteScripts $siteScript.Id

Updates the Site Design title & scripts without recreating it.

Step 8: Remove a Site Design or Site Script

1. Remove a Site Script

Remove-PnPSiteScript -Identity $siteScript.Id

2. Remove a Site Design

Remove-PnPSiteDesign -Identity $siteDesign.Id

Cleans up unused Site Designs & Scripts.

Step 9: Automate Site Design Deployment Using PowerShell Script

To automate Site Design deployment, save this script as DeploySiteDesign.ps1:

# Connect to SharePoint
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com" -Interactive

# Load Site Script JSON
$siteScriptJSON = Get-Content "C:\Path\To\SiteScript.json" -Raw

# Add Site Script
$siteScript = Add-PnPSiteScript -Title "Project Site Script" -Description "Creates a project document library and applies theme" -Content $siteScriptJSON

# Add Site Design
$siteDesign = Add-PnPSiteDesign -Title "Project Site Design" -WebTemplate "64" -SiteScripts $siteScript.Id -Description "Standard Project Site Design"

Write-Host "Site Design Deployment Completed Successfully!" -ForegroundColor Green

Run the script:

PowerShell -ExecutionPolicy Bypass -File "C:\Path\To\DeploySiteDesign.ps1"

Step 10: Schedule Site Design Deployment via Task Scheduler

1️⃣ Open Task Scheduler
2️⃣ Click Create Basic Task
3️⃣ Choose Daily/Weekly Schedule
4️⃣ Choose Start a Program → Enter:

-ExecutionPolicy Bypass -File "C:\Path\To\DeploySiteDesign.ps1"

5️⃣ Click Finish

Ensures automated deployment of Site Designs.

Troubleshooting Common Issues

1. Site Script Not Applying?

Check if the JSON is valid using a JSON validator.
Verify the WebTemplate ID (64 for Team Sites, 68 for Communication Sites).

2. Site Design Not Appearing?

Run Get-PnPSiteDesign to verify the design is created.
Ensure the Site Design is assigned to the correct templates.

3. Permission Issues?

Ensure the user applying Site Designs has Admin or Site Collection Admin rights.