The latest version of the SharePoint Framework (SPFx) released a few weeks ago, v1.7.0, uncovered a few issues between how the various Node.js package managers work. These issues appear to be rooted in the package tslint and came about with a change in how Microsoft was using tslint under the covers from SPFx v1.6 to v1.7.
A fix has been submitted to tslint, but they appear to be lagging on their release schedule so there’s no ETA on when it will get rolled out.
Another issue will have to be fixed in the next release of the SharePoint Framework.
Thankfully there are workarounds that you can employ for the time being that I’ll detail in this post.
NOTE: If you use npm you won’t experience the issue I outline below as npm is a bit more forgiving than Yarn & PNPM.
Issue #1 - tslint rules & unmet peer dependencies
The SPFx engineering team changed the dependency structure for tslint in the latest v1.7 release of SPFx. tslint allows for the creation of custom rules in addition to the rules they include by default. Microsoft has created their own rules and placed them in a reusable package tslint-microsoft-contrib. To use these rules you configure your tslint.json file to specify where other rules can be found.
In the latest SPFx release, Microsoft changed the structure of these packages and how they reference them, moving them to the @microsoft scope. Specifically, they introduced a package @microsoft/sp-tslint-rules that references the tslint-microsoft-contrib package. It appears in doing so, there was a missed peer dependency listed from the tslint-microsoft-contrib on typescript package.
This will get fixed in the next update of SPFx, but at this time there’s no ETA when that will be or if it will be a minor release (like v1.8) or patch release (like 1.7.1). At any rate, this fix is the responsibility of Microsoft.
npm is a little more forgiving from the other package managers, like Yarn & PNPM, so it’s not an issue with those.
Issue #1 workaround
Right now this is only affecting PNPM due to its use of symbolic links. The workaround for issue #3 below will work for this issue as well. To get around it, make sure you include –shamefully-flatten when running pnpm install.
Issue #2: Unmet peer dependencies when using Yarn
Another issue us how Yarn deals with peer dependencies. You see this when you are using Yarn as your package manager and React, specifically the React type declaration files. Yarn is not duplicating packages when it lists any version of a dependent package. What you get is a list of type declaration issues when you try to build your React project using gulp build, as shown in issue SharePoint/sp-dev-docs#2934.
You can learn more about this from the issue yarnpkg/yarn#6695, but from the perspective of the Yarn team, this isn’t something that they should fix, rather it suggests bad behavior. They think the referenced type declaration files should be updated.
Issue #2 workaround
Thankfully there is a workaround for this issue. Open your project’s package.json file and add the following as a peer to the existing dependencies & devDependencies sections:
{
"dependencies": {...},
"devDependencies": {...},
"resolutions": {
"@types/react": "16.4.2"
}
}
If you had already installed your packages with Yarn, delete the node_modules folder and the yarn.lock file, then rerun yarn to reinstall everything. Now, when you build your project, it will work.
Issue #3: Symbolic links when using PNPM
As I explained in my package manager comparison, PNPM uses symbolic links instead of copies of packages to keep the size of your node_modules folders down.
This release of SPFx uncovered a bug in how tslint deals with symbolic links. While the default behavior of Node.js is to resolve & follow symbolic links, tslint was caching/preserving them and isn’t finding custom tslint rules that I referenced in the first issue above.
The good news? Microsoft has already stepped up and fixed this issue with tslint and submitted a PR (palantir/tslint#4295) that’s been approved. However, the team behind tslint is a bit behind on merging PRs and pushing out new versions. So at this point, we’re at the mercy of when they get around to it.
Issue #3 workaround
The fix for this is easy as it’s one we have had to use since Microsoft said they would support different package managers in the SPFx v1.5.1 release. When you install packages, simply include the –shamefully-flatten argument when you run PNPM.
References
There’s a slew of issues in various Github repos that have tracked these issues. If you’re interested in the background story, here you go:
- SharePoint/sp-dev-docs
- palantir/tslint