Version Compatibility Issues When Loading Sharepoint Context In Angular

What is Happening When the Error Occurs

When attempting to load the SharePoint context in an Angular application, a common error encountered is a version incompatibility between the SharePoint framework and Angular. This mismatch prevents the SharePoint libraries and objects from properly loading and integrating with Angular, resulting in context loading failures.

The error typically manifests with a message stating that the SharePoint object model cannot be loaded. For example:

Uncaught TypeError: Cannot read properties of undefined (reading 'ClientSideComponentProperties') at EnsureScriptFuncLoaded (sp-loader_en-us.js:1) at sp-loader_en-us.js:1

Table of Contents

This occurs because the SharePoint sp-loader script expects certain properties and methods to be available on the SharePoint object which are not actually present due to version differences. When Angular tries to interact with the SharePoint context, it runs into these compatibility issues, preventing full integration.

Identifying the Problematic Versions

Pinpointing the source of the version incompatibility requires an understanding of both the SharePoint framework releases and the Angular version requirements.

Overview of SharePoint Framework Versions

The SharePoint framework is updated on a regular basis with new feature releases. Here is a brief overview of some notable versions:

1.1 – Initial release in February 2017
1.2 – Added support for SharePoint 2019 in 2018
1.3 – Deprecated classic web parts in 2018
1.4 – New minor version released every 3 months
1.5 – Continuous integration pipeline for development in 2019
1.6 – Support for scoped custom script extensions in 2019
1.7 – New page experience preview in 2019
1.8 – Support for SharePoint spaces and forms in 2020
1.9 – Updated Fluent UI introduced in 2020
1.10 – Custom form rendering and support for Microsoft Teams tabs added in 2020

Angular Version Requirements

On the Angular side, certain minimum versions are need based on the SharePoint libraries utilized:

@microsoft/sp-core-library – Requires Angular v4+
@microsoft/sp-lodash-subset – Requires Angular v6+
@microsoft/sp-office-ui-fabric-core – Requires Angular v6+
@microsoft/sp-component-base – Requires Angular v8+
Newer minor releases may require more recent Angular versions

Known Incompatible Combinations

Some SharePoint framework and Angular version pairs known to cause integration issues include:

SharePoint 1.7 + Angular 5 – Conflicts due to Fluent UI support
SharePoint 1.8 + Angular 7 – Scoped custom extensions cause crashes
SharePoint 1.10 + Angular 9 – Incompatible Microsoft Teams JavaScript libraries

Fixing the Version Mismatch

Once the incompatible versions are identified, the fix typically involves upgrading one or both in order to restore compatibility.

Upgrading/Downgrading the SharePoint Framework Version

If using an older Angular release (6 or below), downgrading the SharePoint framework version can help resolve conflicts. For example:

npm uninstall @microsoft/sp-core-library npm install @microsoft/[email protected]

This installs a previous service pack release known to work with Angular 6.

Upgrading the Angular Version

When using newer SharePoint framework packages, upgrading Angular is generally required. This can be done via:

ng update @angular/core @angular/cli

Running the Angular CLI updater will fetch the latest compatible releases.

Code Examples of Applying Fixes

To demonstrate resolutions in action, here is a before and after when upgrading Angular to resolve version conflicts:

Before (Error)

// Angular v7 import {Version} from "@microsoft/sp-core-library";

Version.isCompatible(); // throws error

After (Resolved)

// Upgraded to Angular v10 import {Version} from "@microsoft/sp-core-library";

Version.isCompatible(); // checks compatibility successfully

Verifying Compatibility Before Development

Taking preventative measures by validating framework and library compatibility before writing integration code can prevent tricky versioning issues down the line.

Best Practices for Checking Version Compatibility

Some best practices include:

Check release notes and upgrade details for potential breaking changes on updates
Scan documentation for minimum version requirements
Perform small proof of concept tests validating key integration
Monitor community forums and discussion boards for commonly reported issues

Tools for Validating Framework/Library Pairs

In addition to manual checks, tools like npm-check-updates and greenkeeper can automatically validate compatible dependencies:

npm-check-updates – Detects and upgrades package versions, verifying compatibility
Greenkeeper – Monitors packages and open pull requests with upgrades validating compatibility

Recommended Compatibility Matrices

Many frameworks and libraries provide compatibility matrices documenting supported versions:

SharePoint Framework – Supported Angular releases per SPFx version
Angular – Supported 3rd party library versions per Angular release
Community Resources – Compiled compatibility tables across frameworks

Checking these references against your current stack is highly recommended before development.