SymlinkPlugin's behavior has changed since Webpack 5

[mjameswh]

In webpack 4, when SymlinkPlugin identified that a requested path indeed contained a symlink, it would invoke hook relative with the canonical path.

enhanced-resolve/lib/ResolverFactory.js

Line 329 in 2dfe18a

if (symlinks) plugins.push(new SymlinkPlugin("file", "relative"));

However, in Webpack 5, this behavior was changed to:

enhanced-resolve/lib/ResolverFactory.js

Lines 589 to 590 in f08fe3f

	if (symlinks)
	plugins.push(new SymlinkPlugin("existing-file", "existing-file"));

This modification was done in the process of adding support for Yarn PnP, though it seems that this might have been unintentional. See notably sokra's comment on this regard here. It should also be noted that this specific change does not appear in the final PR.

This undocumented change of behavior affects some external plugins that relied on early hooks to be invoked after symlink resolution, notably Gatsby's theme shadowing (see related Gastby issue).

My first impression is that this specific change should be reverted back and I will soon submit a PR in this direction.

On the other side, it means that any plugin that relies on the former behavior would not support Yarn PnP; there might also be a non negligeable performance cost to redo a part of the resolution pipeline after symlink resolution. Consequently, somes could argue that restoring the former behavior is not desirable. If this is indeed the official position, however, then I suggest that this should be clearly mentioned in Webpack release notes.

[sokra]

Symlinks should always point to a really existing file. It's not expected that the resolver do apply resolving logic after that. e. g. a symlink pointing to .../file should not resolve to .../file.js by applying extensions, etc.

So I guess this was a bugfix, but I do not remember it anymore.

[mjameswh]

Symlinks should always point to a really existing file. It's not expected that the resolver do apply resolving logic after that. e. g. a symlink pointing to .../file should not resolve to .../file.js by applying extensions, etc.

Indeed, the default resolver pipeline has no need to apply further resolving logic at that point, but what about custom plugins? Also, I think it's worth pointing out that symlinks may not only be at the file level, but at any level in the path. Notably, package managers use symlinks to provide various advanced feature such workspaces. Until the SymlinkPlugin has been reached, there is no way for a custom plugin to implement logic that require knowledge of the canonical path of the file being resolved.

Now, that being said and after analyzing the code deeper, I don't think that reverting back SymlinkPlugin's behavior is required nor desirable. The plugin that I am concerned with at present (that is, updating Gatsby's implementation of theme shadowing) can be converted to tap on before-resolved instead, which should actually be more reliable (for example, aliases will also have been resolved at that point), and more efficient (ie. previously, the shadowing algorithm would get executed multiple time during the resolution of a single file, where tapping on before-resolved, the algorithm will only get executed twice in the worst case).

Thanks anyway 😉