5 things you need to know about site designs & site scripts

5 things you need to know about site designs & site scripts

1. Site designs are the future of provisioning in SharePoint Online

Site designs allow you to apply actions to a SharePoint Online site. Site designs were introduced in late 2017 and have continued to evolve. They are now at the core of how to help establish consistent configuration for your SharePoint sites across your tenant. You should no longer be using things like ‘Save site as a template’ in either SharePoint Online or on-premises. This is a legacy way to create templates and has limitations in the way they were built compared to site designs. Site designs allow you to empower your end-users with a self-service option for site creation that still allows IT to add governance and consistency.

5 things you need to know about site designs & site scripts blog

Site designs and site scripts are only available in SharePoint Online. If you are working on-premises, it is best to switch your provisioning and/or templating to utilize the PnP Provisioning framework.

If you are in SharePoint Online, whether just getting started or a have all your content out there, now is the time to get going with utilizing site designs.
To get started, here is a quick set of ideas on when you can utilize site designs right away:
• Applying specific configurations on new site creation
• Adding designs that will be applied to default templates
• Updating existing sites with common elements or changes such as:
o Deploy content types to a set of sites
o Enable external sharing
o Apply a theme

2. Site Designs are applied on top of a site collection or subsite

Site designs are fundamentally different than previous versions of OOTB SharePoint provisioning. Site design is a collection of site scripts, and the site scripts are a set of actions, these all require an existing site to exist. So, when a user goes to create a site, what happens is that:
1. A site collection is created based on the actual SharePoint template (STS#3, GROUP#0, etc.)
2. The site scripts within the site design attached to that template are fired against that site collection
The reason this is so important is that you aren’t changing the actual guts or default config of the OOTB template. That means as these templates evolve with the ongoing changes, you still get to receive those changes as the OOTB templates are updated by Microsoft. This ensures the longevity of your sites going forward with all the latest and greatest.
Also, site designs are run when needed. That means as site designs change, the sites where site designs 5 things you need to know about site designs & site scripts blogwere applied to will not get those changes. For example, If I am using a site design for all my project sites which includes the addition of libraries and lists. If I need to make a change to the site design, I would first update the design and deploy it to my tenant. That action will not automatically apply the updated site design to all existing sites. You will need to manually apply the updated site design to all existing sites where that site design had been applied. All new sites will include the updated data from the site design
Overall this means that site designs are not:
o A type of site collection
o Attached to a site and then live there permanently
o A pre-packaged site with everything included
o Only limited to modern SharePoint sites

3. Site designs can be applied beyond just site collection creation

The most commonplace for site designs to be utilized is through the Create Site option on SharePoint ‘Start’ page of your tenant (the page you get when you click the SharePoint app in the app launcher). This is the primary place you can direct your users to self-provision SharePoint sites. Without site designs, there are default templates for Team and Communication sites that your employees can use. Site designs enable you to update the default templates or to add new options for a user to pick from as you can see below.

5 things you need to know about site designs & site scripts blog

This isn’t the only area that site designs can be applied though! Site designs can also be applied:
• When associating a site to a hub site
• On-demand by an end-user through the site design panel
• Through PowerShell or REST
Let’s break each of these down a bit more.

When associating a site to a hub site
SharePoint hub sites are the building blocks for a modern intranet in SharePoint Online. They allow you to logically and technically group site collections. Joanne Klein wrote a great e-book with Valo about building out a modern site architecture that includes the concept of hub sites.
With hub sites, you can pick a site design that will be applied every time a site joins the hub. A great example of this could be applying some SharePoint artifacts to all project sites in your project sites hub such as a project collateral library and project tracker custom list. When a site joins the project site hub, the site design will fire and create the library and the list on the site. As site designs are not destructive nor active after initial application, if that site leaves the hub and joins another, it will not remove any elements and apply a new site design if the next hub site is associated with one. This is a great way to build consistency within a hub site

On-demand by an end-user through the site design panel
The site design information panel can be accessed through the gear icon in the top right of your site. This panel will not only show you the site designs you can apply to your site, but also the site designs have been applied to your site and when that happened. After you run a site design you can see the details of all the actions that occurred within the site design and its status.
As a SharePoint administrator, you can deploy site designs to your end-users so site owners can apply them to their sites. If you do not want this to occur, the site designs must be scoped using the design right options you can set via PowerShell.

5 things you need to know about site designs & site scripts blog

Through PowerShell or REST
If you are building a provisioning solution or just need to programmatically apply site designs to sites, this can be done through the SharePoint Online Management Shell or PnP PowerShell cmdlets or through the SharePoint REST API.

The REST API for calling a site design task is:


4. Multiple site scripts can be included in a single site design

Site design is a collection of site scripts. Site scripts are actions that can be performed on a site. 5 things you need to know about site designs & site scripts blogSite scripts can include things around branding and site settings, apps, solutions, and your core SharePoint components such as libraries, lists, and content types. A full collection of what you can do can be seen in the JSON schema for site scripts.

It is a good idea to have site scripts that you reuse across site designs. One example could be a SharePoint theme. You could build a single site script to apply a theme then every site design you could call that site script vs having a theme in different site scripts across your site designs. That would allow you to change a single spot vs multiple.
Other ideas for reusable site scripts:
• SPFx extensions
o To include the code required for analytics through things like Google or Azure
o Global navigation and/or footer
• Global content types available to all sites that give you options specific to your business or requirements
• Trigger a flow to add an entry to a SharePoint list to track details about sites outside of the admin center
• Add a navigation link to a service request or training/knowledge management center

5. Start using Add-SPOSiteDesignTask to ensure large amounts of actions are handled

When site designs were originally introduced there was a limitation of 30 actions that could be included. This means 30 actions including, sub-actions, and a total of 20,000 characters was the limit. If you tried to utilize one with more than that it would just spin and not actually complete. 30 actions may sound like a good amount but as you start getting into the things like columns this could quickly become an issue.
The support for larger configurations is now available. The number of actions is now 300 or 100,000 characters depending on how the site design is applied. Previously in this article, I mentioned that there are multiple ways to apply a site design. The UI options are being updated to handle the large site design need but as of writing this article, it is not rolled out to all locations.

To programmatically do it through PowerShell the only option previously was to use the Invoke-SPOSiteDesign cmdlet. This cmdlet will instantly run the site design. To handle large site designs the architecture behind the scenes was updated to allow scale. A new cmdlet is now available called Add-SPOSiteDesignTask. This cmdlet does not fire the site design instantly but adds it to a queue and will then run asynchronously behind the scenes.

This queue will still fire in a short period of time but will not be as instant as before. If you are building any other logic in your provisioning that requires the site design to finish you will need to account for the new delay. The REST command to fire a site design mentioned previously utilized the queue and task-based model. You can track the status of the running site designs through PowerShell.

Just to be safe it is a good idea to ensure you are always using the new model to apply site designs, so you don’t accidentally get stuck with provisioning issues. All it takes is to update a site design and unknowingly move it beyond the 30-action limit and have it fail the next time you apply it.

Helpful links to get going with SharePoint Site Designs and Site Scripts
SharePoint site design and site script overview
Get started creating site designs and site scripts
SharePoint site script examples
Site script JSON schema
PnP Provisioning Framework
Set up a site design for your hub site


Valo Intranet makes it easy to have beautiful site design straight out of the box! Want to learn how we can speed up your intranet project without sacrificing quality?


a free demo today!

Would you like to see Valo in action? Fill in this form and we’ll contact you shortly for a quick demo.

We keep your information safe. Read more from our Privacy Policy.