eslint-plugin-isaacscript
eslint-plugin-isaacscript
is a collection of miscellaneous ESLint rules that can help make your JavaScript/TypeScript code more safe or more strict.
This plugin is named after (and used in) the IsaacScript framework. But you don't have to know anything about IsaacScript to use it - you can use these rules with any JavaScript/TypeScript project.
Alternatively, if you want to get off the ground and running with ESLint + TypeScript in a new project, then you should check out the isaacscript-lint
meta-package.
This project is written in TypeScript.
Install / Usage
npm install --save-dev eslint eslint-plugin-isaacscript
- Add
"plugin:isaacscript/recommended"
to theextends
section of your.eslintrc.cjs
file. (This will automatically add the plugin and add all of the recommended rules.)- Alternatively, if you want to only enable some specific rules, then add
"isaacscript"
to theplugins
section of your.eslintrc.cjs
file, and then add the specific rules that you want in therules
section.
- Alternatively, if you want to only enable some specific rules, then add
Configs
-
recommended
- Enables just the recommended rules. (Some rules are not recommended since they are intended for very specific environments.)
Rules
Each rule has emojis denoting:
- ✅ - if it belongs to the
recommended
configuration - 🔧 - if some problems reported by the rule are automatically fixable by the
--fix
command line option - 💭 - if it requires type information
Name | Description | ✅ | 🔧 | 💭 |
---|---|---|---|---|
isaacscript/complete-sentences-jsdoc |
Requires complete sentences for JSDoc comments | ✅ | ||
isaacscript/complete-sentences-line-comments |
Requires complete sentences for multi-line leading line comments | ✅ | ||
isaacscript/consistent-enum-values |
Requires consistent enum values | ✅ | ||
isaacscript/enum-member-number-separation |
Disallows numbers next to letters in enum members | |||
isaacscript/eqeqeq-fix |
Requires the use of === and !== (and automatically fixes) |
✅ | 🔧 | |
isaacscript/format-jsdoc-comments |
Disallows /** comments longer than N characters and multi-line comments that can be merged together |
✅ | 🔧 | |
isaacscript/format-line-comments |
Disallows // comments longer than N characters and multi-line comments that can be merged together |
✅ | 🔧 | |
isaacscript/jsdoc-code-block-language |
Requires a language specification for every JSDoc code block | ✅ | ||
isaacscript/newline-between-switch-case |
Requires newlines between switch cases | ✅ | 🔧 | |
isaacscript/no-confusing-set-methods |
Disallows confusing methods for sets | ✅ | 💭 | |
isaacscript/no-empty-jsdoc |
Disallows empty JSDoc comments | ✅ | 🔧 | |
isaacscript/no-empty-line-comments |
Disallows empty line comments | ✅ | 🔧 | |
isaacscript/no-explicit-array-loops |
Disallows explicit iteration for arrays | ✅ | 🔧 | 💭 |
isaacscript/no-explicit-map-set-loops |
Disallows explicit iteration for maps and sets | ✅ | 🔧 | 💭 |
isaacscript/no-for-in |
Disallows "for x in y" statements | ✅ | ||
isaacscript/no-invalid-default-map |
Disallows invalid constructors for the DefaultMap class | 💭 | ||
isaacscript/no-let-any |
Disallows declaring variables with let that do not have a type | ✅ | 💭 | |
isaacscript/no-mutable-return |
Disallows returning mutable arrays, maps, and sets from functions | ✅ | 💭 | |
isaacscript/no-number-enums |
Disallows number enums | ✅ | ||
isaacscript/no-object-any |
Disallows declaring objects and arrays that do not have a type | ✅ | 💭 | |
isaacscript/no-object-methods-with-map-set |
Disallows using object methods with maps and sets | ✅ | 💭 | |
isaacscript/no-string-length-0 |
Disallows checking for empty strings via the length method in favor of direct comparison to an empty string | ✅ | 💭 | |
isaacscript/no-template-curly-in-string-fix |
Disallows template literal placeholder syntax in regular strings (and automatically fixes) | ✅ | 🔧 | |
isaacscript/no-throw |
Disallows the usage of "throw" | 💭 | ||
isaacscript/no-undefined-return-type |
Disallows undefined return types on functions |
✅ | 💭 | |
isaacscript/no-unnecessary-assignment |
Disallows useless assignments | ✅ | 💭 | |
isaacscript/no-unsafe-plusplus |
Disallow unsafe and confusing uses of the "++" and "--" operators | ✅ | 💭 | |
isaacscript/no-void-return-type |
Disallows void return types on non-exported functions |
✅ | 🔧 | |
isaacscript/prefer-plusplus |
Require "++" or "--" operators instead of assignment operators where applicable | ✅ | 🔧 | |
isaacscript/prefer-postfix-plusplus |
Require "i++" instead of "++i" | ✅ | 💭 | |
isaacscript/prefer-readonly-parameter-types |
Require function parameters to be typed as readonly to prevent accidental mutation of inputs |
✅ | 💭 | |
isaacscript/require-break |
Requires that each case of a switch statement has a break statement |
✅ | ||
isaacscript/require-capital-const-assertions |
Requires a capital letter for named objects and arrays that have a const assertion | ✅ | 🔧 | |
isaacscript/require-capital-read-only |
Requires maps/sets/arrays with a capital letter to be read-only | ✅ | 💭 | |
isaacscript/require-unannotated-const-assertions |
Disallows explicit type annotations for variables that have a const assertion | ✅ | ||
isaacscript/require-v-registration |
Require variables named "v" to be registered with the save data manager | 💭 | ||
isaacscript/require-variadic-function-argument |
Requires that variadic functions must be supplied with at least one argument | ✅ | 💭 | |
isaacscript/strict-array-methods |
Requires boolean return types on array method functions | ✅ | 💭 | |
isaacscript/strict-enums |
Disallows the usage of unsafe enum patterns | ✅ | 💭 | |
isaacscript/strict-undefined-functions |
Disallows empty return statements in functions annotated as returning undefined | ✅ | 💭 | |
isaacscript/strict-void-functions |
Disallows non-empty return statements in functions annotated as returning void | ✅ |
Automatic Fixing
You probably already use Prettier, which is helpful to automatically format files. You probably even have your IDE set up to run Prettier every time your save a file. This kind of thing saves you a tremendous amount of time - you can type out a bunch of code completely unformatted, and then press Ctrl + s
at the end to automatically fix everything. (Alternatively, you could press Ctrl + shift + f
to format the file without saving it, but it's simpler to just use one hotkey for everything.)
In a similar way to Prettier, this ESLint plugin contains several rules that are designed to automatically apply whenever you save the file (like the format-jsdoc-comments
rule). These rules are "fixers", which are applied when ESLint is executed with the "--fix" flag. So, in the same way that you configure Prettier to run on save, you should also configure eslint --fix
to run on save.
For example, if you use VSCode, and you have the Prettier and the ESLint extensions installed, you can add the following to your repository's .vscode/settings.json
file:
{
// Automatically run the formatter when certain files are saved.
"[javascript]": {
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit"
},
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.tabSize": 2
},
"[typescript]": {
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit"
},
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.tabSize": 2
}
}
Comment Formatting
For a discussion around comments and the motivations for some of the comment rules in the plugin, see this page.
Contributing
Thanks for helping out with this open-source project!
If you are adding a new rule, start by using the create-rule
script to automate a few things:
npm run create-rule foo "This is a description of the foo rule."
git status # Show what the script did.
Additionally, You can contact me on Discord if you are doing a PR and have questions.