eslint-plugin-tree-shaking
Marks all side-effects in module initialization that will interfere with tree-shaking
Last updated 7 months ago by lukastaegert .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install eslint-plugin-tree-shaking 
SYNC missed versions from official npm registry.

eslint-plugin-tree-shaking

Marks all side-effects in module initialization that will interfere with tree-shaking

npm JavaScript Style Guide Greenkeeper badge semantic-release

Usage

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).

JavaScript:

myGlobal = 17
const x = {[globalFunction()]: 'myString'}

export default 42

Rollup output:

myGlobal = 17;
const x = {[globalFunction()]: 'myString'};

var index = 42;

export default index;

ESLint output:

1:1   error  Cannot determine side-effects of assignment to global variable
2:13  error  Cannot determine side-effects of calling global function

This plugin is most useful when you integrate ESLint with your editor.

Installation and Setup

You'll first need to install ESLint:

$ npm i eslint --save-dev

Next, install eslint-plugin-tree-shaking:

$ npm install eslint-plugin-tree-shaking --save-dev

Note: If you installed ESLint globally (using the -g flag) then you must also install eslint-plugin-tree-shaking globally.

Add tree-shaking to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{
    "plugins": [
        "tree-shaking"
    ]
}

Then add the rule no-side-effects-in-initialization to the rules section:

{
    "rules": {
        "tree-shaking/no-side-effects-in-initialization": 2
    }
}

Rollup compatibility mode

If you are using rollup.js, you should activate the rollup compatibility mode that will flag additional issues that prevent tree-shaking in rollup:

{
    "rules": {
        "tree-shaking/no-side-effects-in-initialization": [
            2, {"compatibility": "rollup"}
        ]
    }
}

E.g. JavaScript:

class x {}
new x()

ESLint output:

1:1   error  [Rollup specific] Calling a ClassDeclaration is a side-effect

Magic Comments

ESLint only ever analyzes one file at a time and by default, this plugin assumes that all imported functions have side-effects. If this is not the case, this plugin supports magic comments you can add before identifiers in imports and exports to specify that you assume an import or export to be a pure function. Examples:

  • By default, imported functions are assumed to have side-effects:

    JavaScript:

    import {x} from "./some-file";
    x()
    

    ESLint output:

    1:9  error  Cannot determine side-effects of calling imported function
    
  • You can mark a side-effect free import with a magic comment:

    JavaScript:

    import {/* tree-shaking no-side-effects-when-called */ x} from "./some-file";
    x()
    

    No ESLint errors

  • By default, exported functions are not checked for side-effects:

    JavaScript:

    export const x = globalFunction
    

    No ESLint errors

  • You can check exports for side-effects with a magic comment:

    JavaScript:

    export const /* tree-shaking no-side-effects-when-called */ x = globalFunction
    

    ESLint output:

    1:65  error  Cannot determine side-effects of calling global function
    

Background and Planned Development

This plugin is in early development. If you want to contribute, please read CONTRIBUTING.md.

This plugin implements a side-effect detection algorithm similar to what rollup uses to determine if code can be removed safely. However, there is no one-to-one correspondence as this is also meant as an example implementation of what such an algorithm could do. For instance, this algorithm is able to identify if the instantiation of a class has side-effects, something that rollup has not implemented yet.

Therefore to make this plugin actually useful to library developers, it sports a rollup compatibility mode. If you find that you have code that

  • is not removed by rollup (even though tree-shaking is enabled) but
  • has no ESLint issues even though you use rollup compatibility mode

please--if no-one else has done so yet--check the guidelines and file an issue!

Planned improvements:

  • There is no webpack compatibility mode yet. The plan is to add this eventually but if you want to speed things up, please contribute.

Current Tags

  • 1.7.4                                ...           latest (7 months ago)

15 Versions

  • 1.7.4                                ...           7 months ago
  • 1.7.3                                ...           a year ago
  • 1.7.2                                ...           2 years ago
  • 1.7.1                                ...           2 years ago
  • 1.7.0                                ...           2 years ago
  • 1.6.1                                ...           2 years ago
  • 1.6.0                                ...           2 years ago
  • 1.5.0                                ...           2 years ago
  • 1.4.1                                ...           2 years ago
  • 1.4.0                                ...           2 years ago
  • 1.3.0                                ...           2 years ago
  • 1.2.0                                ...           2 years ago
  • 1.1.1                                ...           2 years ago
  • 1.1.0                                ...           2 years ago
  • 1.0.0                                ...           2 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 1
Last Day 0
Last Week 0
Last Month 3
Dependencies (0)
None
Dev Dependencies (12)

Copyright 2014 - 2016 © taobao.org |