Best Practices For Reliably Including Javascript And Css Across Sharepoint Online Pages

The Core Problem of Inconsistently Rendered Web Parts

A common frustration for SharePoint Online administrators and page editors is getting custom JavaScript (JS) and Cascading Style Sheets (CSS) to consistently load and apply across page layouts. Despite carefully adding script editor or content editor web parts to pages, the imported JS and CSS files often fail to properly render web parts. Troubleshooting page inheritance settings across site collections is cumbersome and unreliable for fixing these rendering issues.

The main culprits behind inconsistently rendered web parts are complex inheritance chains that make it challenging to predict how user permissions, site themes, page layouts, and custom scripts ultimately interact. Tenant-wide policies and galleries can override site-level customizations, resulting in web parts that inexplicably shift format or stop functioning with their associated JS and CSS dependencies.

Optimize Page Layouts for Custom Scripts

The most effective way to support custom JS and CSS injections is to optimize page layouts for these external dependencies. This involves configuring the precise level where new site designs and scripts should be inherited while restricting assets from broader galleries. Tenant admins have granular control over inheritance behavior in SharePoint Online sites, site collections, and at the tenant level.

Table of Contents

By default, anything deployed to a SharePoint tenant gallery gets inherited everywhere below it. Items added to site level asset libraries similarly flow down through all sites and pages contained in the site automatically. To promote consistency, administrators can allow certain custom scripts and stylesheets at site collections or individual sites while blocking other inherited assets. Page layouts can also be restricted to isolate and troubleshoot rendering issues with web parts pulling in problem scripts from parent sites or galleries.

Manual Embedding vs. Bundles

Beyond configuring inheritance settings, SharePoint pages have two main options for including JS and CSS: manual embedding with script editor web parts and managed bundles. Manually entering references to script libraries directly in page editor web parts provides maximal control. However, this approach also scales poorly, quickly becoming cumbersome across many pages and sites.

Alternatively, JS and CSS files can be grouped into bundle (.SPBundle) files that act as centralized containers for maintaining multiple page dependencies. Bundle files reside in asset libraries and can conveniently inject multiple script and stylesheet references in one line of code. The main limitation with bundling is the difficulty troubleshooting conflicts between different versions of bundled libraries.

Recommended Practices

Reliably incorporating JS and CSS in SharePoint Online involves several best practices:

Add scripts and stylesheets using dedicated script editor web parts inserted directly before closing page body tags
Link to widely-used libraries on public CDN servers instead of local copies when possible
Standardize page layouts, script bundles, and embedded libraries across sites

Following these recommendations significantly improves web part rendering consistency. Script editor parts provide isolation from other content on the page. CDN libraries minimize conflicts between local asset library copies. Standardizing page layout customizations, scripts, and stylesheets also reduces unexpected interference across SharePoint sites.

Example Embed Codes

Sample embed code for popular JS library jQuery from the Google CDN:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.1/jquery.min.js"></script>

Example CSS stylesheet link inside a content editor web part:

<link rel="stylesheet" type="text/css" href="/stylelibrary/css/mysite.css">

For advanced troubleshooting, temporarily reference protocol-less sources to identify errors loading resources from mixed content paths:

 
<script src="//ajax.google.apis.com/ajax/libs/jquery/3.6.1/jquery.min.js"></script>

Testing and Deployment Strategies

Rigorously testing custom scripts and stylesheets is critical before broadly deploying to many pages across a SharePoint tenant. Confirming cross-browser compatibility and performance across desktop and mobile screens will minimize issues.

Gradually rolling out major page layout changes through controlled testing groups is another proven approach for catching bugs. Monitoring page load analytics will identify problems to address before inflicting them on all users.

With deliberate testing and incremental deployment, even substantial customizations can be added reliably within SharePoint Online for optimal web part presentation across sites.