Putout

Perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away.

(c) Antoine de Saint Exupéry

🐊Putout is a JavaScript Linter, pluggable and configurable code transformer, drop-in ESLint replacement with built-in code printer and ability to fix syntax errors. It has lots of transformations that keeps your codebase in a clean state, removing any code smell and making code readable according to best practices.

The main target is JavaScript, but:

• ✅ JSX;
• ✅ TypeScript;
• ✅ Yaml;
• ✅ TOML;
• ✅ Markdown;
• ✅ JSON;
• ✅ Ignore;

are also supported. Here is how it looks like:

Table of contents

• 🤷‍♂️ In doubt about using 🐊Putout?
• 🙏 Whom should I thank for this project exist?
• 🤷‍♂️ Why does this project exist?
• 🪬Core Concepts
• 🚚 Installation
• 🎙 Usage
• 🦕 Usage with Deno
• 📐 What is Ruler?
• ✂️ How Ruler can help me?
• 🚁 Convert CommonJS to ESM
• 🏛 Architecture
• 🌲 The Tree of Syntax
• 🌴 Laws of the Jungle
• 🏗 API
• 🏨 Built-in transformations
• 🛠️ Syntax errors
• 🐃 Operators
• 🏟 Plugins
• 🦚 Formatters
• 🦉 Configuration
• 🧬 Plugins API
• 🛴 codemods
• 💾 rulesdir
• ⏣ Integration with ESLint
• ☄️ Integration with Babel
• 🐈 Integration with Yarn
• ⛓ Using Putout as Loader
• 🚪 Exit Codes
• 🦔 Real-world uses
• 📻 Versioning policy
• 🚀 I want contribute
• 🍄 License

🤷‍♂️ In doubt about using 🐊Putout?

Check out couple variants of plugins that does the same: linting debugger statement:

• ❌ SWCLint no-debugger: 49 lines;
• ❌ RSLint no-debugger: 48 lines;
• ❌ ESLint no-debugger: 43 lines;
• ❌ Rome no-debugger: 28 lines;
• 🐊 Putout remove-debugger: 5 lines:

export const report = () => `Avoid 'debugger' statement`;

export const replace = () => ({
    debugger: '',
});

Choose wisely, competitors cannot even fix… 🤫

Drop-in ESLint replacement

🐊Putout in addition to own format .putout.json supports both eslint.config.js and .eslintrc.json, it has ability to autodect format you use. Also it works good with monorepository, since it uses eslint.config.js that is closer to linting file, instead of cwd of ESLint run.

🙏 Whom should I thank for this project exist?

If I have seen further, it is by standing upon the shoulders of giants.

(c) Isaac Newton

• 💪ESLint for stable releases and future proof API.
• 💪Babel for amazing API documented in Handbook and responsiveness of a team.
• 💪Prettier for minimalistic options and uniform codestyle.
• 💪JSCodeshift for making codemods simple and popular.

🤷‍♂️ Why does this project exist?

• ❌ESLint avoids fixes that could change the runtime behavior.
• ❌Babel has no ability to report errors, it only runs transformations.
• ❌Prettier is a formatter.
• ❌JSCodeshift has no config and plugins support.

🐊Putout on the other hand can make more drastic code transformations that directly affects your codebase making it a better place to code 💻:

• ✅ fixes Reference Errors;
• ✅ declares variables;
• ✅ converts CommonJS to ESM;
• ✅ ...and much more 😏!

🚚 Installation

To install 🐊Putout as a development dependency, run:

npm i putout -D 

Make sure that you are running a relatively recent (≥16) version of Node.

🎙 Usage

Grown-ups never understand anything by themselves, and it is tiresome for children to be always and forever explaining things to them.

(c) Antoine de Saint-Exupéry

🐊Putout tries to be clear and likes a lot to explain things. So when you write putout --help most likely you will hear gladly purr :

Usage: putout [options] [path]
Options:
   -h, --help                  display this help and exit
   -v, --version               output version information and exit
   -f, --format [formatter]    use a specific output format, the default is: 'progress-bar' locally and 'dump' on CI
   -s, --staged                add staged files when in git repository
   -i, --interactive           set lint options using interactive menu
   --fix                       apply fixes of errors to code
   --fix-count [count = 10]    count of fixes rounds
   --rulesdir                  use additional rules from directory
   --transform [replacer]      apply Replacer, for example 'var __a = __b -> const __a = __b', read about Replacer https://git.io/JqcMn
   --plugins [plugins]         a comma-separated list of plugins to use
   --enable [rule]             enable the rule and save it to '.putout.json' walking up parent directories
   --disable [rule]            disable the rule and save it to '.putout.json' walking up parent directories
   --enable-all                enable all found rules and save them to '.putout.json' walking up parent directories
   --disable-all               disable all found rules (set baseline) and save them to '.putout.json' walking up parent directories
   --match [pattern]           read '.putout.json' and convert 'rules' to 'match' according to 'pattern'
   --fresh                     generate a fresh cache
   --no-config                 avoid reading '.putout.json'
   --no-ci                     disable the CI detection
   --no-cache                  disable the cache
   --no-worker                 disable worker thread

To skip prefix node_modules/.bin/, update your $PATH variable in with .bashrc:

echo 'PATH="$PATH:node_modules/.bin"' >> ~/.bashrc
source ~/.bashrc

To find possible transform places in a folder named lib, run:

putout lib

To find possible transform places in multiple folders, such as folders named lib and test, run:

putout lib test

To apply the transforms, use --fix:

putout lib test --fix

☝️Commit your code before running 🐊Putout

Developers, myself included, usually prefer to make all code changes manually, so that nothing happens to our code without reviewing it first. That is until we trust a tool to make those changes safely for us. An example is WebStorm, which we trust when renaming a class or a method. Since 🐊Putout may still feel like a new tool, not all of us will be able to trust it immediately.

A good way to gain trust is two run without --fix option, and observe e