DEV Community: icy0307

浏览器兼容性代码

icy0307 — Tue, 22 Aug 2023 09:21:07 +0000

如何处理浏览器的兼容性代码和包大小息息相关。

polyfill的通常意义, 在wiki上是这么说的.

💡 In web development, a polyfill is code that implements a feature on web browsers that do not natively support the feature. Most often, it refers to a JavaScript library that implements an HTML5 or CSS web standard, either an established standard on older browsers, or a proposed standard on existing browsers.

然而在现实世界上，领域不同还有不同的jargon（黑话）。了解这些黑话和不同的黑话对于领域范围对处理包大小的实际问题非常有意义。

JS

当我们在讨论js相关的polyfill的时候，实际在说什么？

js的兼容性代码总共需要考虑两大块内容，ECMAScript和web standards api。其中ECMAScript又分为两大部分: 语言的syntax和语言所指的功能。另外浏览器，还有web api提供的能力.

语言的syntax：如 arrow function, spread operator, async await , generator

语言的feature:• 如ECMAScript: Reflect, Array.prototype.includes

web standard: 如 setTimeout and setInterval

这对工具有什么影响？

工具分为两大类：compiler 和 polyfill library

compiler如： Babel, TypeScript, esbuild(vite和webpack会处理关于module类的syntax)

polyfill library如：core-js, es-shim, tslib等

compiler 负责让modern syntax 在现代浏览器工作。他们将浏览器不支持的syntax, 通过一些helper function（@bable/helpler, tslib），转成浏览器能认识的样子。

polyfill library的任务是让native function能工作。es-shim如他的名字一样，支持 ECMAScript里的feature. 而core-js除此之外还支持部分web api。

babel一类的compiler可以对代码进行分析，并自动根据对应的浏览器，通过polyfill provider选择import合适的polyfill library,如core-js或es-shim ，将依赖注入。

如何打包这些polyfill

polyfill and ponyfill

在详述如何打包polyfill之前，我们要先解释一个概念： ponyfill

💡 A ponyfill
is almost the same as a polyfill, but not quite. Instead of patching functionality for older browsers, a ponyfill provides that functionality as a standalone module you can use

根据polyfill和ponyfill的分类，我们就有两种打包方式。其中polyfill指的是指global context的，可能会污染全局。ponyfill指的是不会污染全局没有副作用的版本。

一个典型的例子就是 core-js和 core-js-pure

import 'core-js/actual/promise';// 含有副作用的全局polyfill
import Promise from 'core-js-pure/actual/promise'; //无副作用的局部polyfill.如果引用不存在，这部分会被dead code remove

如何打包

For App

对于APP来说。一般来说我们可能不怕全局污染（当作为微前端应用的一部分就要重新考虑)。

最原始的做法

最原始的做法是：所有的polyfill的直接在应用入口文件定义。
例如在polyfill-io上，选择你需要的polyfill,生成一个“polyfill.min.js”，并在html所有script开始前引用它。
或者使用babel，将要用的功能插件，例如"@babel/plugin-transform-spread”枚举出来。
这个做法的问题在于，靠人工制定哪个环境下需要哪些功能。需要人工知道哪些浏览器支持ECMA的哪些标准，并不方便放弃或增加对于浏览器的支持。如果node_modules里有人用了什么不知道的feature,代码就没有经过polyfill.

改进的做法

工业化的第二个改进，是引入类似browserlist的声明。在package.json或其配置文件里声明需要对哪些浏览器起效。

    // package.json
    {
      "browserslist": [
        "last 1 version",
        "> 1%",
        "not dead"
      ]
    }

在入口处引入polyfill.例如“import "core-js";”. 然后compiler根据browserlist里的声明。将目标浏览器下缺失的每个功能列出来。全局polyfill, 使得后面的代码无需引入polyfill也能直接引用。

    import "core-js/modules/es.string.pad-start";
    import "core-js/modules/es.string.pad-end";

这就是babel/preset-env的useBuiltIns: 'entry'的或babel-polyfills系列的"method": "entry-global"行为。
在入口文件根据目标浏览器，把可能用到的每一个ECMAScript feature引入。这样的好处是，只需要在入口处声明一次，并且方便更改浏览器支持。如果某个包没有参与app的编译也无所谓。因为所有的功能都在入口文件列出了。
但这样也同样带来了问题，由于没有分析代码用到了哪些feature，所以需要把所有功能在入口列出。
这样虽然根据浏览器裁剪了部分polyfill，但任然不符合模块化的要求，代码可能很后面才用到或者压根用不到，造成首屏和整体包体积膨胀。譬如core-js，gzip后任然有70kB。这些polyfill是全局副作用，还会占据首屏运行时间。

最好的做法

最佳的做法是用到什么引入什么。babel这样的compiler分析这个库的所有代码(包括node_modules)。根据分析结果, 将引用插入每个文件开头。


    // 源文件
    foo.flatMap(x => [x, x+1]);
    // babel-plugin-polyfill-corejs3 usage-pure 转换后, 不污染全局
    _flatMapInstanceProperty(foo).call(foo, x => [x, x + 1]);
    // babel-plugin-polyfill-corejs3 usage-global
    // 或preset-env useBuiltIns: 'usage'转换后 污染全局
    import "core-js/modules/es.array.flat-map.js";
    foo.flatMap(x => [x, x + 1]);

这样减少了文件执行时间和文件大小。由于是app, 我们可以选择在全局进行polyfill。

babel该如何配置

使用@babel/preset-env避免手工枚举plugin, 注意proposal需要单独声明出来。
如果需要全局polyfill,使用@babel/preset-env的 useBuiltIns: 'usage'或[babel-plugin-polyfill-corejs3](https://github.com/babel/babel-polyfills/blob/main/packages/babel-plugin-polyfill-corejs3)的usage-global。后者是前者最新用法的代替。区别在于原来只能使用corejs作为polyfill。现在可以自己指定polyfill-provider。譬如你还可以使用[babel-plugin-polyfill-es-shims](https://github.com/babel/babel-polyfills/blob/main/packages/babel-plugin-polyfill-es-shims)/
如果需要局部ponyfill,使用[babel-plugin-polyfill-corejs3](https://github.com/babel/babel-polyfills/blob/main/packages/babel-plugin-polyfill-corejs3)的usage-global。
使用@babel/plugin-transform-runtime来避免helper代码重复。一定要注意version与所使用的runtime版本匹配。这部分会造成非常可观的代码膨胀。

作为库作者如何打包

最好的方式莫过于不打包。不去预设用户需要哪些polyfill。因为知道用户需要什么的只有用户自己。一旦预设的polyfill超出了用户的需要，就会造成不需要的代码被下载。库应该参与项目的构建。

不过现实是大部分为了使用者方便，很多项目polyfill提前引用或打包。虽然这是不被推荐的行为。如果真的需要这么做的话，仍然要注意：

使用ponyfill而不是polyfill，不要污染全局。
使用babel/plugin-transform-runtime来，并把 @babel/runtime, core-js 声明为dependency(不是peer dep或者dev dep), 并注意 不要打包。
库一般会提供多个target, 如cjs，es5,es2015等等，shippedProposals, esm等选项都要做出相应的改变。
version字段与你使用的runtime版本匹配。因为默认值是@babel/runtime@7.0.0，会造成版本不匹配，进而导致本该inject helper的地方，代码直接内连。例如regenerator的boilerplate代码就特别多。

一个完整的例子：

//babel.config.js
{
  "presets": [
    ["@babel/preset-env", { // 根据browser list进行polyfill
      "targets": { "firefox": 42 }
            "modules": useESModules ? false : 'commonjs',//根据你的构建产物判断是否使用esm
    }]
  ],
  "plugins": [
    ["@babel/transform-runtime", {// 不是每个文件都插入代码，而是从@babel/runtime/helpers import
            useESModules //根据你的构建产物判断是否使用esm
            version: '^7.4.4', // 不要使用默认版本，避免无法inject造成代码膨胀
        }],
    ["polyfill-corejs3", { 
      "method": "usage-pure" // 用ponyfill
    }]
  ]
}

ECMAScript syntax

打包方式基本和上文说的一致，需要区分app和library

typescript, babel都可以进行转换。

需要注意的是，babel/runtime或tslib都需要显示的声明成production dependencies. 并使用上文提到的@babel/plugin-transform-runtime来避免重复代码

WEB API

core-js提供一部分web-api的实现。

但web-api的问题在于，这部分功能大多数需要浏览器支持，不支持可能就是没有办法实现。所以当你用一个功能的时候，先在CANIUSE上判断您的大多数用户是否可以使用，并提供降级方案。

Css

不同的浏览器下，对css的支持也有差异。通常用prefix来区分。例如 “-moz”代表mozilla旗下的fire-fox, -webkit代表苹果使用的webkit. 分清哪些场景使用哪些属性，单靠手工在caniuse查询依然十分不可靠。我们可以使用css中的polyfill： autoprefixer 同样根据browserlist自动完成。

Browserlist的角色和问题

browserlist可以方便我们更新支持的browser，并且所有工具链都可以根据统一的target来统一完成对目标浏览器的适配。

例如，defaults的默认值是> 0.5%, last 2 versions, Firefox ESR, not dead

browserlist的数据来自于caniuse-lite。可以使用[update-browserslist-db](https://github.com/browserslist/update-db)来定期更新。

所以我们需要提交lock, 指出browserlist依赖的caniuse-lite版本，否则不同构建产生的polyfill都可能不一样。

另外一个应用可能含有很多仓库。对于同一个项目，使用shared-config来让各个项目统一。

ref:

https://en.wikipedia.org/wiki/Polyfill_(programming)

http://es6-features.org/#StatementBodies

https://github.com/babel/babel/issues/10008#user-content-annex-b

https://github.com/babel/babel/discussions/14443

https://github.com/babel/babel/issues/9853

http://es6-features.org/#BinaryOctalLiteral

https://github.com/zloirock/core-js/labels/web standards

https://caniuse.com/

https://babeljs.io/docs/babel-plugin-transform-runtime

关键资源加载实践

icy0307 — Tue, 22 Aug 2023 05:49:16 +0000

作为开发人员，您知道哪些文件最重要。你可以提前标记这些关键资源，加快加载过程。

本文介绍了如何达成此目的。

包括：

预加载资源在真实世界的应用场景。

何时以及如何使用preload。

如何在你的构建工具中标记这些关键资源，以及现有方案的不足。

发现问题

在一个应用里，我们发现当前页面真实能响应用户交互的时间非常晚。

让我们用一张图视图化这个问题

为了使的client side渲染进行快速响应，渲染和响应交互的事件分了包，当用户渲染的脚本开始执行时，才会触发响应用户交互资源的加载。

const button = <Button onclick=async() => {
                await import('/.real-click-response');
// This is the real time to interactive that user feel
}/>
render(button);

而这些代码里，可能会有其他响应交互所需的资源被进一部分包。这部分资源，在前面下载的资源实际开始执行的时候才被发现。

这个被称为sequential network requests问题。

在真实世界里，网络环境越差，造成的结果就越严重。这个问题可以在performance面板被发现。典型的特征是，主线程是空的，没有要处理的内容。空闲时间和下载时间正好好差不多。并且下一个任务正是 evaluate刚刚下载的script.

怎么做预加载

我们期望可以达成这样的目标。

在网络请求有余力的时候，提早下载接下来的重要资源。

错误的做法❌

实践中，有些人可能会在浏览器空闲的时候，尝试await import马上需要的资源。在应用的开头加入如下的话

requestIdleCallback(() => {
         await import('./resource-need-pretty-soon');
});

这个错误的原因在：

我们期望的是触发他的下载，而不是执行。import会触发文件的evaluation。执行写在该文件top level的语句。这可能会非常耗时，取决于你引入的module在top level写了多少自执行代码。实际观察中，最差可能会出现500ms以上。

client side render 以及应用初始化的时候，可能会产生很多微任务。我们不期望待会才需要的文件的evaluation会发生在 client side render的任何任务之前。

预加载只应该占用网络线程的空闲资源而不是主线程的资源。

没那么好的做法

自定义preload implementation，如fetch API。

fetch需要被调用它的script在download, parse, compile, evaluate后才能被看见，实际上也产生了sequential network requests。即使inline了script，仍然需要compile 和执行。这仍然没有我们接下来要介绍的做法效率高。

正确的做法

幸运的是，浏览器提供了[rel=preload的](https://web.dev/preload-critical-assets/)标签，去触发资源的下载。

虽然名字里有个load，但他只会触发下载和缓存，并不会真正执行。

具体可以被preload的资源，和该标签支持的属性可以参考mdn的描述，在此不加以赘述。

但是关于preload，以下有一些你需要注意的事：

1. Don’t preload everything

只preload那些你知道接下来绝对会使用到的资源。把不需要的资源preload只会浪费用户带宽。另外一次性preload过多的资源，可能会造成资源竞争。

如果资源下载下来后，大概三秒没有用到，浏览器会出以下告警。

如果下一个页面或者navigation才需要的资源，您可能需要的是prefetch.

2. 有必要preload在html的script吗？

在html嵌入的资源我们称之为initial assets，有些资源是动态加载的(譬如await import的资源)。我们称其为 async assets.

script标签有可能会出现在body的末尾，我们需要对这些 initial assets 增加preload标签吗？

通常不需要。

现代浏览器的html parser 在阻塞资源面前的确会暂停。例如不是async，defer或者module的script标签，或是link下载的stylesheet。

但是同时他会有一个另一个html parser: preload scanner，提前发现当前页面里需要的资源。所以刚刚说到的，放在body末尾的script标签也会被发现，即使前面有阻塞资源。所以是没必要对这些资源加preload标签的。

然而，目前的preload scanner只作用于html。假设你的css会触发字体下载，或者需要背景图片。那即使这些是渲染关键资源的确也发现不了。如果这是阻碍您性能的关键问题，的确可以尝试preload这些资源。

如果你的关键渲染资源被异步加载。用script去加载另一些js和css资源，preloads scanner就会不起作用。如果执行加载的script前面有block资源（例如首屏css), sequential network request依然存在。即使你尝试使用preload标签，这些加载preload标签的script也只会在blocking resource执行完才开始运行。

这种sequential network request被称为 critical request chains, 我们应该避免它。

所以比起preload标签，请先确认一定要用script去下载关键渲染资源吗？为什么不是直接把它们inline到html里？

3. 会重复下载吗

会，如果你不足够小心。

preload会下载，并且放入缓存。但是有时，preload资源和下载的资源并不会复用，触发double-fetch。这不仅代表你做的preload优化没用，还代表浪费了用户的带宽。

这就是仔细阅读preload属性的必要时候了

一定要带上as属性。as描述了要被下载的资源类型，会影响Accept request header, request匹配等等。更重要的是 as还确定了preload 资源的fetch priority。

关于preload资源的priority详细可以参看此表。
预加载的字体如过没用crossorigin attribute 会被加载两次
如果使用了integrity，一些浏览器下不支持

Addy Osmani关于double fetch问题有非常出色的文章。

4. import preloads 只应该在下载他们的资源开始被import的时候才开始触发。

import preload, 包括 dynamic import() 或 modulepreload，preload资源的时机应该在加载他们的script被加载之后。确保加载他们的script顺序是在前面的。script A 加载script B。只要scriptA被加载的时候scriptB才被需要。尤其是modulepreload除了下载缓存以外，还会compile指定的资源。

如何在工程里使用preload

在现代项目里，我们通常会使用打包工具将项目里的module组合成更大的文件，也就是bundle。所以在源码中，构建过程还未完成，我们是不可能自己加link标签的。所以我们需要借助打包工具将我们需要预加载的资源用link preload预加载。

对于bundler原理其实很相似，但值得注意的是vite会有auto preload的功能。不过问题依旧是相似的。

以下将用webpack 做一下说明：

什么是关键资源其实需要我们自己决定, webpack利用事先定义好的comment来约定用户如何告诉webpack这是需要被preload的文件。也可以告诉webpack他的优先级是什么

import(
/* webpackPreload: true */
/* webpackFetchPriority: "high"*/
 "CriticalChunk")

在构建的时候，他会解析到这个comment，明白用户想要加载这个module。于是这个module所属于的chunk group都会被预加载。

不仅包含这个module本身，也包含这个module直接依赖的其他资源，如css，依赖的其他module等。

加载的时机是由webpack runtime，在require引入preload的资源的文件的时机加载，也就是加载他们的script被加载时。

只在需要的时候preload

所以以下场景，不应该加preload标志

// Don't do this
if (someRuntimeCondition) {
    import(_/* webpackPreload: true */_ "CriticalChunkA")
} else {
    import(_/* webpackPreload: true */_ "CriticalChunkB")
}

由于bundler只能静态分析，他并不知道RuntimeCondition在runtime的值是什么。所以他无法判断需要preload哪个文件，只好两个都下载，这会极大程度浪费用户带宽.

在这个场景下我们该怎么做？

it depends.

对于关键资源，可以在服务端触发主动下载。

如果我们可以不依赖客户端知道这个condition是什么，并且我们可以确定这个资源关键关键路径一定会用到。

我们可以事先把构建工具产生的bundle信息上传，在服务器预先判断好条件，通过不同条件下发不同bundle。

这时会有两种方式: Server push 和 html 上附加<link rel=preload>。

Server push是http2 的一个新功能。他的一般做法是，在服务器上在html头部添加

link:</push.css>; as=style; rel=preload

如果server支持它，就会把他看作要push的对象。否则客户端就会把它视为一个preload assets。如果你使用了cdn，cdn也要支持。

另一个做法是下发html的上拼接<link rel=preload>

这两个做法的关键区别在：

server push不需要依赖preload scanner. 所以原理上他会快一点点（但preload scanner本身也不慢）
server push 的资源很容易被浪费。如果他已经push下来，但还没有被任何请求认领这个http session就被关闭的话，push缓存就没有了。如果这个请求已经在客户端缓存的话，server是没有办法知道的，依然push下来，造成带宽的浪费。

另外，即使不在服务器上，也可以在浏览器运行的任何时间被添加。

综上所述，可能大部分时间拼接<link rel=preload>是个比较好的方法。

在entrypoint不起效

下面这段代码不会生效，这和webpack的生态有关。

async function main() {
    const { awaitImportByInitialChunk } = await import(/* webpackPreload: true */ './await-imported-by-intial-chunk');
    awaitImportByInitialChunk();
}

main();

webpack runtime只会去加载被其他dynamic import的文件await import 的资源。

正如上文所说，被preload的资源下载的时机，应该是加载它的文件被触发加载之后。而initial chunk是在html上通过script标签下载的。所以这种的位置就应该在这个script标签之后，html上。

在webpack的生态里，这是由其插件https://github.com/jantimon/html-webpack-plugin 完成。

遗憾的是，这个功能还没有被实现。不过html-webpack-plugin本身是支持插件的，所以我们可以自己实现它。（还未发布）

避免会触发资源竞争的写法

在实际生产中，还发现一种会让自动添加可能是负效果的写法。

假设当前的应用分几个关键的stage加载自身。

// entry.js
const firstStageResources = [
    import(/* webpackPreload: true */'./1'),
    import(/* webpackPreload: true */'./2'),
    //...
    import(/* webpackPreload: true */'./10'),
];
const secondStageResources = [
    import(/* webpackPreload: true */'./11'),
    import(/* webpackPreload: true */'./12'),
    //...
    import(/* webpackPreload: true */'./20'),
];
const thirdStageResources = [
    import(/* webpackPreload: true */'./21'),
    import(/* webpackPreload: true */'./22'),
  //...
    import(/* webpackPreload: true */'./30'),
];

function load(resources) {
        Promise.all(preloadResources)
}

function async load() {
    await load(firstStageResources);
    await load(secondStageResources);
    await load(secondStageResources);
}

我们假设想要预下载其中的文件，对每个import()都做了preload标记，会发现由于所有的动态import其实都由一个文件加载。当这个文件是entry，也就是html加载的initial chunk的时候，所有资源会一起被preload下来。

本身优先级很低的标签，甚至高过页面本身就有的initial script 标签，造成和其他资源的竞争。如果不改变这种pattern继续preload, 在资源紧张的时候可能是种负优化。

我有serviceWorker了，preload link有效吗

service worker 在fetch事件的时候，进行拦截。

如果cache里面没有，依旧可以访问http cache(disk cache)。这时如果已经preload资源就会存在在http cache里。依旧避免了网络请求的时间。所以整体来说，这仍然有意义。

另外根据Jake Archibald这篇文章，preload有独立的cache, 优先级会更高。导致被preload的资源，在资源原本被请求的位置发出请求时，不会走到service worker。

Addy Osmani的文章也提到如果这个文件是cacheable将会放入http cache, 如果不是甚至会被提升到memory cache。memory cache将比从disk里读的效率更高。

另外如果是 module preload，preload的资源甚至已经被compile好。

所以无论从何种角度上来说，preload都能和service worker一起使用，并在sequential request的场景下，起到性能提升作用。

总结

不要使用import预加载，import实际会让代码执行，使用自带的preload机制做预加载
只预加载过会一定要用到的资源，预加载的时机是想要加载预加载模块的代码被加载时。
首屏资源没有必有主动添加，让preload scanner帮助你
没有办法使用preload scanner的情况，可以在构建工具里标注，动态的内容可以在服务器帮助判断。如果entryPoint发现标注preload失效，可以使用我们提供的webpack插件
避免double fetch，或者触发资源竞争的写法

ref:

https://web.dev/preload-scanner/

https://developer.chrome.com/zh/docs/lighthouse/performance/critical-request-chains/

https://web.dev/fetch-priority/#conclusion

https://medium.com/reloading/preload-prefetch-and-priorities-in-chrome-776165961bbf

https://sking7.github.io/articles/332630583.html

https://www.keycdn.com/blog/http2-push

https://medium.com/webpack/link-rel-prefetch-preload-in-webpack-51a52358f84c

Peer Dependencies in depth

icy0307 — Tue, 22 Aug 2023 05:27:49 +0000

TL;DR:

The peerDependencies field is not for single copy of a package.
Use peerDependencies when your host app needs a compatible version of another package to work with the library you provide. If your library doesn't have such constraints, list them as dependencies instead.
The peerDependencies field is meant to warn you of any incompatibilities, so resolve unmet peer errors instead of ignoring them.
As the library author, make both your dependencies and peerDependencies ranges as wide as possible.
Do not overuse peerDependencies. Otherwise, library users will have difficulty resolving compatibility problems or may have to resort to ignoring them altogether.

Introduction

If you have worked with node packages, you might have come across the term "peer dependency."

However, I've noticed that some of my colleagues tend to think that peer dependencies are only for singletons or that **they guarantee a single copy* in final bundles* so the final code size could be smaller. However, this isn't quite accurate.

In this blog post, we will explore what peer dependencies are, how they differ from dependencies, and how package managers like 'npm' work with them. This post will also cover how to resolve peer dependencies conflict and best practice to de-duplicate package’s copy.

What are Peer Dependencies?

💡 peerDependencies field is designed to be used for declaring compatibility requirements between a library and other libraries used by the host app.

In order to understand what peer dependencies are, we need to understand why they are needed in the first place and why dependencies are not enough.

So why dependencies are not good enough?

Dependencies work fine in terms of "compatibility". If a package you are building requires library foo version 1.0.0, and your app depends on foo@2.0.0, your code will work fine as there are two copy of foo.

├── foo@2.0.0
└─┬ your-library@1.2.3
└── foo@1.0.0

However, certain packages depend on other packages that must be installed by the user in order to function properly. If a package requires the presence of other packages, it is likely designed to be used with specific versions of those packages. If the installed versions are not compatible, an error should be thrown to alert the user to choose a compatible version instead of silently installing multiple versions as a sub-folder (as the dependencies field does). This ensures that the library can work correctly with the host package.

For example, consider the following structure:



├── react-dom@16.0.0
└─┬ your-library@1.2.3
  └── react@17.0.0

Your library is a UI component library made with React. In order to work in a DOM environment, the react package needs to be rendered by react-dom, which should be installed in the root project using a method like root.render(<App />). Depending on your code, your UI component library may have some constraints on the version of react-dom, even though react-dom is not required in your library's source code. For instance, your library uses React hooks, so the react-dom library that mounts it must above version 16.8.0 .

If only using dependencies field, the react-dom would present inside your library folder. But this is futile because react-dom@17.0.0 is not the package that the host app uses to render your react component.



├── react-dom@16.0.0 // this is the package the host app use to provide 'render' API
└─┬ your-library@1.2.3
  └── react@17.0.0
  └── react-dom@17.0.0 // this is futile, since this is not the react-dom actually being used.

This is when react-dom should be a peer dependency.

Let’s look into another scenario, when react need to be a a peer dependency.



├── react-dom@16.0.0
├── react@16.0.0 
└─┬ your-library@1.2.3
  └── react@17.0.0 // incompatible with host app version

The project install your library has already has react as dependency.react that your library uses needs to be the same version as the one installed by the user, so that hooks can work properly. In order to use your library, the host app’s react version must be updated. The user must be informed of this!!! Hence, the use of peer dependencies.

How Are Peer Dependencies Different From Dependencies?

As mentioned above, when deciding whether to list a package in dependencies or peerDependencies, the only thing that should be taken into consideration is whether it imposes compatibility constraints on other libraries that the host app is using or must install.

This means that the peerDependencies field is not for a singleton or single copy in the final bundle(We will explore how to achieve this later on).

Let's consider a question: should react and react-dom be listed as dependencies or peerDependencies?

The answer is: it depends.

Wait a second, did you just mention in the previous section that react and react-dom are peer dependencies? Yes, but that assumption was based on the idea that you are building a React-based UI library that provides React components for the host app to render. What if your library is a UI library that doesn't require react-dom to render and only adds rendered DOM to the outside DOM that the user provides? The use of React is relevant only to the library and does not impose any constraints on other packages installed by the user. Furthermore, the host app does not need to install any other packages for the library to work. Therefore, react and react-dom are dependencies that matter only to you: the library author. You may change your implementation to Vue or Svelte at any time.

Here is a little quiz:

Should lodash be a peer dependency or dependency?
Should tslib be a peer dependency or dependency?
Should rollup be a peer dependency or dependency?

What about multiple copies of package?

Does this mean that if we use the dependencies field, we may end up with multiple copies of the same package installed?

Yes, if the versions are mismatched. This is also true for peerDependencies, except it won't resolve correctly by design.

As a matter of fact, react does support having multiple copies on the same page. This is important because having multiple copies ensures that all code works properly, even if the package version they rely on doesn't match. For example, if the host app is using a different version of lodash than the library is using, and there are breaking changes between these two versions, two copies are needed to ensure the code runs correctly.

Furthermore, bundlers like webpack have some bundle rules that cause multiple copies even though there is only one copy of a package in node_modules tree.

Library has no way to ensure there is only one copy of package in final bundles or that the object inside library is singleton by modifying package json. The only correct way to create a singleton object is by adding a flag in the global scope.The number of copies in the node_modules folder is not determined by dependencies or peerDependencies, but by the package versions of the packages.

So make sure your packages follow the semantic versioning rule for bothdependencies and peerDependencies , and make it as wide as possible like "^1.0" or "1.x", instead of "~1.0.4" or "1.0.4" .For packages with a version below "1.0.0", the number in the middle represents the possibility of changes that break backward compatibility. If you know that such changes will not occur, you may use "<1.0.0" instead. Then the host app can use command like dedupe to deduplicate dependencies with overlapping ranges.

What should we do when conflicts occur with peer dependencies?

Should we ignore it?

If you have read the previous section, you now understand that peer dependency is a way to warn you that the packages you installed may not work with other packages you installed. Of course, you should resolve it instead of ignoring it.

Unfortunately, in npm versions 3 through 6, peerDependencies were completely ignored when building a package tree. Even today, both npm and pnpm have the strict-peer-deps flag set to false by default, which ignores indirect peers. This can cause packages to receive a peer dependency outside the range set in their package's peerDependencies object, potentially leading to bugs.

Using -force and -legacy-peer-deps is a shameful last resort, as it might break your code.

But how to resolve it exactly?

Before diving into how to resolve it, check whether the library really should list the conflicting package as a peer dependency causing so much trouble.

If not, ask the author to change it into the dependencies field, and ask the author to make the version of the package as broad as possible.

If it should be listed in peerDependencies:

dependency is below what peerDependencies require:

Just update the required dependency.

dependency is above what peerDependencies require:

If possible, ask the library author to update its peer dependencies. Alternatively, you can downgrade the dependencies of the host application. Asking author to update might be the only solution in some cases when versions really are incompatible and you cannot afford to downgrade.

Sometimes a library may be unmaintained, but still working. In such cases, you may know that broadening the version of peerDependencies would not cause any compatibility issues. Alternatively, you may realize that the peerDependencies it requires should not even be a peerDependencies in the first place, but making the author understand this may take forever. Fortunately, your package manager provides a convenient way to avoid such hassle.

For npm above 8, you can use overrides field in package.json



  "overrides": {
    "react": "$react"
  }

For pnpm, there more choices:

pnpm.peerDependencyRules.allowedVersions or some other related flag in package.json



{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "react": "17"
      }
    }
  }
}

Pnpm installation hook: hooks.readPackage(pkg, context): pkg



const peerDependencies = ['peerDependency1', 'peerDependency2'];
const { overrides } = rootPkg.pnpm;
function overridesPeerDependencies(pkg) {
    if (pkg.peerDependencies) {
        for (const dep of peerDependencies) {
            if (dep in pkg.peerDependencies) {
                pkg.peerDependencies[dep] = overrides[dep];
            }
        }
    }
}

module.exports = {
    hooks: {
        readPackage(pkg, _context) {
            // skipDeps(pkg);
            overridesPeerDependencies(pkg);
            return pkg;
        },
    },
};

However pnpm.overrides isn’t working now.

For yarn, sadly there is no way to do it for the time being, you can track this issue for future possibility.

Other Things You Should Know About Peer Dependencies

“missing peer” usually mean auto installation has been turned off, check out corresponding package manager doc for detail.
peer dependencies are transitive.

If packageX has a dependency on packageY, and packageY has a peer dependency on packageZ, then packageZ is also a peer dependency of packageX. This chain can continue until some package acts as the host.

These can cause implicit problems, such as: having two copies of exact same version packages in pnpm monorepo, or a mismatch between babel plugins and babel version due to babel preset.
peer dependencies can be optional. See this page for more details.

Conclusion

In conclusion, peer dependencies are an essential part of creating and maintaining a library to ensure compatibility with other packages used in a host application. They are not meant for singleton or single copy in the final bundle, and their use should be carefully considered to avoid unnecessary conflicts and inconvenience for users. For users, it is crucial to resolve conflicts when they occur rather than ignoring them. For library authors, it is recommended to use peer dependencies only when necessary and be lenient **in version requirement. This post has become much longer that I intended to, so we will talk about how to resolve multiple packages copies in future post.

Ref:

https://docs.npmjs.com/cli/v9/configuring-npm/package-json/#peerdependencies

https://docs.npmjs.com/about-semantic-versioning

https://nodejs.org/en/blog/npm/peer-dependencies

https://dev.to/arcanis/implicit-transitive-peer-dependencies-ed0

https://stackoverflow.com/questions/64573177/unable-to-resolve-dependency-tree-error-when-installing-npm-packages

https://github.com/pnpm/pnpm/issues/4214

https://github.com/yarnpkg/berry/issues/4099

https://dev.to/arcanis/implicit-transitive-peer-dependencies-ed0

https://github.com/npm/rfcs/blob/main/implemented/0025-install-peer-deps.md