Provisioning Consistent SharePoint Team Sites with Site Scripts and Site Designs

The Problem: Repeated Manual Site Setup

When teams need a new SharePoint team site for a project, administrators or power users often repeat the same steps: create a site, add a custom list for tracking, apply the corporate theme, and grant permissions to a specific Azure AD group. Doing this manually leads to drift, missed steps, and wasted time.

How Site Scripts and Site Designs Work

A site script is a JSON document that defines a set of allowed SharePoint PnP PowerShell or REST actions that run during site creation. It can create lists, apply themes, set permissions, and install SPFx solutions. A site design bundles one or more site scripts with metadata (title, description, image URL) and surfaces the design in the SharePoint UI when creating a modern team or communication site.

Allowed Actions

• Create SharePoint lists or libraries
• Apply a theme from the tenant theme gallery
• Grant permissions to Azure AD groups or users
• Add SPFx solution to the site
• Set site properties (title, description)

Worked Example: Project Tracker Site Design

The following steps show how to create a site script that adds a custom “Project Tracker” list, applies the tenant’s corporate theme, and grants the site to the Azure AD group ProjectManagers. Then we attach the script to a site design for self‑service provisioning.

1. Author the site script JSON

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/site-script-action.schema.json",
  "actions": [
    {
      "verb": "createSPList",
      "listName": "Project Tracker",
      "templateType": 100,
      "description": "List for tracking project tasks and milestones",
      "enableContentTypes": true,
      "fields": [
        {"fieldType": "Text", "displayName": "Project Name", "internalName": "ProjectName"},
        {"fieldType": "DateTime", "displayName": "Due Date", "internalName": "DueDate"}
      ]
    },
    {
      "verb": "applyTheme",
      "themeName": "Corporate Theme"
    },
    {
      "verb": "grantPermissions",
      "principalId": "ProjectManagers",
      "roleDefinition": "Contribute"
    }
  ],
  "bindata": {},
  "version": 1
}

Save this JSON to a file, e.g., project-tracker-script.json.

2. Upload the script and note its ID

Run the following SharePoint PnP PowerShell command as a tenant administrator:

Connect-SPOService -Url https://contoso-admin.sharepoint.com
$scriptId = Add-SPOSiteScript -Path .\project-tracker-script.json -Title "Project Tracker Script"
Write-Host "Script ID: $scriptId"

3. Create the site design

Add-SPOSiteDesign -Title "Project Tracker Site" \
    -Description "Creates a team site with a Project Tracker list, corporate theme, and ProjectManagers permissions" \
    -SiteScriptIds $scriptId \
    -WebTemplate "64" \
    -PreviewImageUrl "https://contoso.sharepoint.com/sites/siteassets/project-tracker-preview.png" \
    -IsDefault:$false

The -WebTemplate "64" value corresponds to the modern team site template.

4. Provision a site using the design

In the SharePoint home page, click **+ Create site**, choose **Team site**, then under **Pick a template** select **Project Tracker Site**. After the site is created, verify:

• The list “Project Tracker” exists with the two columns.
• The corporate theme is applied (check the site colors).
• The Azure AD group ProjectManagers has Contribute permission on the site.

Trade‑offs and Limitations

• Site scripts must finish within 30 seconds; longer actions are throttled or fail.
• Only tenant administrators can upload and manage scripts/designs; end users can only apply existing designs.
• Scripts cannot modify classic SharePoint sites or run arbitrary code beyond the allowed PnP actions.
• Because scripts are immutable after upload, any change requires a new script version and updating the associated site design, which can complicate version control if not tracked.

Getting Started and Verification

To verify that a script was stored correctly, retrieve it and compare to the original JSON:

Get-SPOSiteScript -Identity $scriptId | ConvertTo-Json -Depth 5

Similarly, list designs:

Get-SPOSiteDesign | Where-Object {$_.Title -eq "Project Tracker Site"} | Format-List Title, Description, SiteScriptIds

After provisioning a site, run a quick check with PnP PowerShell:

Connect-SPOService -Url https://contoso-admin.sharepoint.com
Get-SPOSite -Identity https://contoso.sharepoint.com/sites/ProjectSiteA | Get-SPOList | Where-Object {$_.Title -eq "Project Tracker"}

If the list returns, the design executed as intended.

By codifying repeatable site creation steps into site scripts and designs, you eliminate manual drift, speed up provisioning, and give business users a self‑service way to launch consistently configured team sites.