tree_shaking/no-side-effects-in-initialization Nursery
What it does
Marks all side-effects in module initialization that will interfere with tree-shaking.
This plugin is intended as a means for library developers to identify patterns that will interfere with the tree-shaking algorithm of their module bundler (i.e. rollup or webpack).
Why is this bad?
Side-effects in module initialization can hinder tree-shaking, which aims to remove unused code. If side-effects exist, it's harder for the bundler to safely eliminate code, leading to larger bundles and potentially unexpected behavior. Ensuring minimal side-effects allows bundlers to optimize code effectively.
Examples
Examples of incorrect code for this rule:
myGlobal = 17; // Cannot determine side-effects of assignment to global variable
const x = { [globalFunction()]: "myString" }; // Cannot determine side-effects of calling global functionExamples of correct code for this rule:
const localVar = 17; // Local variable assignment, no global side-effects
export default 42; // Pure export with no side-effectsOptions
{
"rules": {
"tree-shaking/no-side-effects-in-initialization": [
2,
{
"noSideEffectsWhenCalled": [
// If you want to mark a function call as side-effect free
{ "function": "Object.freeze" },
{
"module": "react",
"functions": ["createContext", "createRef"]
},
{
"module": "zod",
"functions": ["array", "string", "nativeEnum", "number", "object", "optional"]
},
{
"module": "my/local/module",
"functions": ["foo", "bar", "baz"]
},
// If you want to whitelist all functions of a module
{
"module": "lodash",
"functions": "*"
}
]
}
]
}
}Magic Comments
Besides the configuration, you can also use magic comments to mark a function call as side effect free.
By default, imported functions are assumed to have side-effects, unless they are marked with a magic comment:
import { /* tree-shaking no-side-effects-when-called */ x } from "./some-file";
x();@__PURE__ is also supported:
import { x } from "./some-file";
/*@__PURE__*/ x();