We recently lost our developer that setup our webpack config and I'm trying to fix a couple issues but I'm finding the Webpack 4 tree shaking documentation confusing.

First, I'll mention the two issues in case you can easily offer a solution.

1. In production mode, our font paths are wrong.
2. In production mode, a sprite png with an scss file specifying styles to position properly on the file has the wrong URL to the sprite png.

Of course everything works properly in development mode.

I understand, conceptually, tree shaking but I'm getting confused with the settings.

From the Tree Shaking doc here: (https://v4.webpack.js.org/guides/tree-shaking/)

package.json sideEffects

The second paragraph at the end says:

The new webpack 4 release expands on this capability with a way to provide hints to the compiler via the "sideEffects" package.json property to denote which files in your project are "pure" and therefore safe to prune if unused.

That makes it sound to me like files/patterns added to package.json's sideEffects property are the ones that are safe to prune, i.e. safe to tree shake.

However, on the same page in the "Mark the file as side-effect-free" section it says "If your code did have some side effects though, an array can be provided instead:".

This sounds like the opposite. The files that are NOT safe to tree shake go in the sideEffects property.

Also, we had an issue a few days ago where we noticed we were losing some styling in a Vue SFC (.vue) file, which we assumed to be due to tree shaking, and adding *.vue to the sideEffects array resolved the problem.

I see other places on the same page where it looks like sideEffects is for files that are not safe for tree shaking, which makes sense for the name of the property. For example this:

A "side effect" is defined as code that performs a special behavior when imported, other than exposing one or more exports. An example of this are polyfills, which affect the global scope and usually do not provide an export.

So is the second paragraph of the Tree Shaking just worded backwards?

Webpack production config optimization sideEffects property vs package.json sideEffects property?

I have found that setting the optimization sideEffects to false in our webpack.prod.config file resolves both the font path and sprite png file path. That seems to me that it is therefore not tree shaking. But setting it to false seems linguistically like I'm saying none of my files have side effects so prune any you want. That seems to be the opposite of my observed behavior.

The documentation here https://v4.webpack.js.org/configuration/optimization/#optimizationsideeffects says:

Tells webpack to recognise the sideEffects flag in package.json ...

[As un unrelated side note, that section includes a blue info panel that says "Please note that sideEffects should be in the npm module's package.json file and doesn't mean that you need to set sideEffects to false in your own project's package.json which requires that big module." HUH? I cannot figure out what that is trying to tell me. What big module?]

That makes it sound to me like setting it to false should tell webpack to ignore the sideEffects in package.json. Which also makes it seem then that webpack should use it's default behavior for tree shaking which I interpret (but can't find definitively stated anywhere) to be that it will attempt to tree shake everything? Yet, the opposite seems to be true because when I set webpack.prod.config optimization.sideEffects to false, neither of my two problem exist making me think they have not been tree shook.

Also, the rest of the quote from above continues as:

... or rules to skip over modules which are flagged to contain no side effects when exports are not used.

This again makes it sound like package.json's sideEffects are the files that are safe to tree shake?

So I'm missing something. Any clarity and enlightenment would be greatly appreciated.