SharePoint Framework (SPFx) projects are written in TypeScript. For a while, developers were stuck using the version of TypeScript specified by Microsoft with each SPFx release. In the SPFx v1.8 release, the version of TypeScript was decoupled from the project so that now you can use any version you like, provided there’s a supported option. In this post, I’ll explain how this works, what versions of TypeScript you can use and how to implement it in your project.
The relationship between the SPFx development toolchain & TypeScript
Before I dive into this topic, I want to first explain why it’s not as simple as just updating the your project to a different TypeScript version. SPFx projects, or more correctly stated - the entire build toolchain, is built on multiple dependencies from multiple teams across Microsoft. These dependencies, things such as gulp tasks, are all written in TypeScript and used by multiple projects & teams, not just the SPFx team & projects.
When you build a SPFx project, there are multiple things built at the same time and these projects all need to be built in a specific order. Microsoft uses a home-grown tool, Rush, to build multiple projects in the desired order. Rush is similar to the popular tool Lerna that accomplishes much of the same thing.
So… SPFx projects, Rush, TypeScript… how do they all come together?
Rush Stack Compiler - decoupling the TypeScript compiler
For a while, up through the SPFx v1.7 release, the version of TypeScript was tied to the project. But in SPFx v1.8, the version of TypeScript was decoupled from the project by introducing a new npm package: The Rush Stack Compiler.
The Rush Stack Compiler isn’t just one package, but a series. There’s a different version available for each version of TypeScript. You can tell which version of TypeScript each version is tied to by the name of the package. For example, @microsoft/rush-stack-compiler-3.3 uses TypeScript v3.3.
SPFx & the Rush Stack Compiler
Each SPFx project can specify the version of TypeScript to use. In the current version of SPFx, version 1.11, the default project is configured to use TypeScript v3.3.
The TypeScript version must be set in two places:
The appropriate Rush Stack Compiler project must be installed and set as a dependency, ideally a
devDependency, in the project.Take care to use the correct version that I specify below as some package versions don’t work with the SPFx project or it’s toolchain dependencies. In the code below, notice that while we’re using TypeScript 3.3 and the corresponding Rush Stack Compiler, notice we’re using version v0.3.5. There are multiple version of @microsoft/rush-stack-compiler-3.3 and not all work with the SPFx project or it’s toolchain, but v0.3.5 does work, so you want to be specific.
SPFx project’s package.json:
{ "devDependencies": { "@microsoft/rush-stack-compiler-3.3": "0.3.5", } }The baseline tsconfig.json TypeScript compiler settings
The TypeScript compiler settings are set in one of two ways. Either you set them as arguments when you run the compiler, or you can set them in a project file. This project file, tscconfig.json is passed into the TypeScript compiler (TSC) when you run it.
All SPFx projects contain a tscconfig.json file at the root. This file takes a default project file and extends it with additional values for a SPFx project. The default that’s extended is coming from the Rush Stack Compiler that’s installed. Notice the path to the file contains the Rush Stack Compiler name, which includes the version of TypeScript in the name.
SPFx project’s tsconfig.json:
{ "extends": "./node_modules/@microsoft/rush-stack-compiler-3.3/includes/tsconfig-web.json", "compilerOptions": { .. } }
HOWTO: Change the TypeScript Version for your SPFx Projects
When you want to change your project to use a different version of TypeScript from what you get out of the box, you need to do three things:
Uninstall the existing Rush Stack Compiler from your project.
npm uninstall @microsof/rush-stack-compiler-3.3Install the desired version of the Rush Stack Compiler for your project. Take care to use an exact version and don’t include any of the special characters in the version that npm adds, such as
~or^. These tell npm “you can install a more recent version if one has been released”. Do this by adding the –save-exact argument to the npm install command:npm install @microsoft/[email protected] --save-dev --save-exactManually update the tsconfig.json file in your project by changing the
extendsproperty to point to the path to the new Rush Stack Compiler package you installed:SPFx project’s tsconfig.json:
{ "extends": "./node_modules/@microsoft/rush-stack-compiler-3.9/includes/tsconfig-web.json", "compilerOptions": { .. } }
Whenever making changes to plumbing like this, I like to do a clean install of my dependencies. Do this by deleting the node_modules folder and delete the package-lock.json file before re-running npm install. I’ve noticed the above steps sometimes remove the TypeScript compiler from the dependencies & the installation of a new Rush Stack Compiler doesn’t add it back. However, simply reinstalling everything cleanly will fix that issue.
SPFx supported Rush Stack Compiler versions
The fun part of this process is knowing which version of TypeScript & the Rush Stack Compiler will work with SPFx projects! Here’s a list that’s based on what Microsoft has stated is supported in their release notes for SPFx v1.8 (up to TypeScript v3.3), as well as what the community has figured out since then.
TypeScript v2.7
SPFx v1.8.0 projects started using this version as the default TypeScript version.
@microsoft/rush-stack-compiler-2.7 v0.5.7
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v2.9
SPFx v1.8.2 projects started using this version as the default TypeScript version.
@microsoft/rush-stack-compiler-2.9 v0.6.8
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.0
@microsoft/rush-stack-compiler-3.0 v0.5.9
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.3
SPFx v1.10 projects started using this as the default TypeScript version.
@microsoft/rush-stack-compiler-3.3 v0.1.6
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.4
@microsoft/rush-stack-compiler-3.4 v0.8.37
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.5
@microsoft/rush-stack-compiler-3.5 v0.8.37
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.6
@microsoft/rush-stack-compiler-3.6 v0.6.37
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.7
SPFx v1.12.1 projects started using this version as the default TypeScript version.
@microsoft/rush-stack-compiler-3.7 v0.6.37
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.8
@microsoft/rush-stack-compiler-3.8 v0.4.37
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v3.9
SPFx v1.13.0 projects started using this version as the default TypeScript version.
@microsoft/rush-stack-compiler-3.9 v0.4.37
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v4.5
SPFx v1.15.0 projects started using this version as the default TypeScript version.
@microsoft/rush-stack-compiler-4.5 v0.2.2
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v4.7.4
SPFx v1.18.0 projects started using this version as the default TypeScript version.
@microsoft/rush-stack-compiler-4.7 v0.1.0
npm install @microsoft/[email protected] --save-dev --save-exact
TypeScript v4+ can only be used in SPFx projects v1.15 and higher. This is due to the underlying dependencies in the SPFx build toolchain..
TypeScript v5.3
Microsoft has not officially said that the SPFx supports TypeScript v5.3, however it does seems to work just fine in my testing with SPFx v1.19 & SPFx v1.20.
Consider this experimental.
To use TypeScript v5.3, you’ll need to make a few extra changes to your project.
@microsoft/rush-stack-compiler-5.3 v0.1.0
# remove the current RSC from the project... for example, if you're using v4.7... npm uninstall @microsoft/rush-stack-compiler-4.7 --save-dev --save-exact # upgrade TypeScript, ESLint, and add the TypeScript v5.3 RSC npm install [email protected] --save-dev --save-exact npm install [email protected] --save-dev --save-exact npm install @microsoft/[email protected] --save-dev --save-exact
Update the Associated RSC Version in Tsconfig.json
If you change the version of TypeScript on your SPFx project, make sure you update the version referenced in the project’s tsconfig.json file:
{
-- "extends": "./node_modules/@microsoft/rush-stack-compiler-4.7/includes/tsconfig-web.json",
++ "extends": "./node_modules/@microsoft/rush-stack-compiler-5.3/includes/tsconfig-web.json",
"compilerOptions": {
"target": "es5",
"forceConsistentCasingInFileNames": true,
...
}
}
When building your project, you may see this error:
Error - [tslint] no-use-before-declare is deprecated. Since TypeScript 2.9. Please use the built-in compiler checks instead.
As it states, the TSLint rule no-use-before-declare is deprecated and you shouldn’t use it any longer. To remove this error, locate this rule in the project’s ./tslint.json file and delete it.
Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.
Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 20+ year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught. Whether it’s an introduction to the entire ecosystem, or a deep dive into a specific software, his resources, tools, and support help web developers become experts in the Microsoft 365 ecosystem, so they can become irreplaceable in their organization.
