For an existing template that already has this config setup, please refer to the roblox-ts template repository. This includes all necessarily files and configurations to get you up and running.
We provided a CLI tool to help you set up your project, or migrate from the legacy config to the new flat config with one command.
npx @isentinel/eslint-config@latest
If you prefer to set up manually:
pnpm i -D eslint @isentinel/eslint-config
With "type": "module"
in package.json
(recommended):
// eslint.config.ts
import style from "@isentinel/eslint-config";
export default style();
Note that
.eslintignore
no longer works in Flat config, see customization for more details.[!TIP] ESLint can support .ts config files, but requires some additional setup. See here for more information.
Create a tsconfig.build.json
file in the root of your project with the
following content:
{
"extends": "./tsconfig.json",
"include": ["src/**/*", "eslint.config.ts"]
}
This is required to allow typescript to work with the ESLint configuration file, without erroring due to it not being included in the project.
For example:
{
"scripts": {
"lint": "eslint .",
"lint:fix": "eslint . --fix"
}
}
Many of the rules in this config are designed to work with the following options set:
{
"noUncheckedIndexedAccess": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true
}
The ts/no-non-null-assertion
rule is enabled by default, which will warn you
when you use the !
operator to assert that a value is not undefined
. The
caveat is that this rule will not always play nicely with
noUncheckedIndexedAccess
, and will often require you to disable it in certain
places. I believe that this is a good trade-off, as it will help you catch
potential bugs in your code, but you can disable it if you find it too restrictive.
{
"rules": {
"ts/no-non-null-assertion": "off"
}
}
Install VS Code ESLint extension
Add the following settings to your .vscode/settings.json
:
{
// Enable the ESlint flat config support
"eslint.experimental.useFlatConfig": true,
"editor.formatOnSave": false,
// Auto fix
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "always",
"source.organizeImports": "never"
},
// Silent the stylistic rules in you IDE, but still auto fix them
"eslint.rules.customizations": [
{ "rule": "style/*", "severity": "off", "fixable": true },
{ "rule": "format/*", "severity": "off", "fixable": true },
{ "rule": "*-indent", "severity": "off", "fixable": true },
{ "rule": "*-spacing", "severity": "off", "fixable": true },
{ "rule": "*-spaces", "severity": "off", "fixable": true },
{ "rule": "*-order", "severity": "off", "fixable": true },
{ "rule": "*-dangle", "severity": "off", "fixable": true },
{ "rule": "*-newline", "severity": "off", "fixable": true },
{ "rule": "*quotes", "severity": "off", "fixable": true },
{ "rule": "*semi", "severity": "off", "fixable": true }
],
// Enable eslint for all supported languages
"eslint.validate": [
"typescript",
"typescriptreact",
"markdown",
"json",
"jsonc",
"yaml",
"toml"
],
// Currently required to enable .ts config files
"eslint.options": { "flags": ["unstable_ts_config"] }
}
Normally you only need to import the style
preset:
// eslint.config.ts
import style from "@isentinel/eslint-config";
export default style();
And that's it! Or you can configure each integration individually, for example:
// eslint.config.ts
import style from "@isentinel/eslint-config";
export default style({
// `.eslintignore` is no longer supported in Flat config, use `ignores`
// instead
ignores: [
"./fixtures",
// ...globs
],
// Provide TypeScript parser options for access to type checking lints.
typescript: {
parserOptions: {
project: "tsconfig.build.json",
},
},
// Disable yaml support
yaml: false,
});
The style
factory function also accepts any number of arbitrary custom config overrides:
// eslint.config.ts
import style from "@isentinel/eslint-config";
export default style(
{
// Configures for this config
},
// From the second arguments they are ESLint Flat Configs
// you can have multiple configs
{
files: ["**/*.ts"],
rules: {},
},
{
rules: {},
},
);
Check out the configs and factory for more details.
Thanks to antfu/eslint-config and sxzz/eslint-config for the inspiration and reference.
Since flat config requires us to explicitly provide the plugin names (instead of the mandatory convention from npm package name), we renamed some plugins to make the overall scope more consistent and easier to write.
New Prefix | Original Prefix | Source Plugin |
---|---|---|
import/* |
i/* |
eslint-plugin-i |
node/* |
n/* |
eslint-plugin-n |
yaml/* |
yml/* |
eslint-plugin-yml |
ts/* |
@typescript-eslint/* |
@typescript-eslint/eslint-plugin |
style/* |
@stylistic/* |
@stylistic/eslint-plugin |
When you want to override rules, or disable them inline, you need to update to the new prefix:
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+// eslint-disable-next-line ts/consistent-type-definitions
type foo = { bar: 2 }
This config includes the CSpell plugin by default, which
will warn you when you have misspelled words in your code. This can be useful
for catching typos, and ensuring that your code is consistent. Roblox keywords
are also included in the dictionary, which is provided by the
cspell-dicts-roblox
package. If any words roblox words are missing, please open an issue on that
repository rather than this one.
Sometimes you will have words that are not in the dictionary, but are still
valid for your project. To add these words to the dictionary, you can create a
cspell.config.yaml
file in the root of your project with the following content:
# cspell.config.yaml
words:
- isentinel
- isverycool
To disable this, you can set the spellCheck
option to false
:
// eslint.config.ts
import style from "@isentinel/eslint-config";
export default style({
spellCheck: false,
});
For more information on how to configure the spell checker, please refer to the CSpell documentation.
perfectionist
(sorting)This plugin eslint-plugin-perfectionist
allows you to sorted object keys, imports, etc, with auto-fix.
The plugin is installed and some rules are enabled by default, but these rules can be disabled or overridden by your own config. For example, I personally have sort-objects set to:
// eslint.config.ts
import style from "@isentinel/eslint-config";
export default style({
rules: {
"perfectionist/sort-objects": [
"warn",
{
"custom-groups": {
id: "id",
name: "name",
"react-props": ["children", "ref"],
},
groups: ["id", "name", "unknown", "react-props"],
order: "asc",
"partition-by-comment": "Part:**",
type: "natural",
},
],
},
});
We provide some optional configs for specific use cases, that we don't include their dependencies by default.
To enable React support, you need to explicitly turn it on:
// eslint.config.ts
import style from "@isentinel/eslint-config";
export default style({
react: true,
});
Running npx eslint
should prompt you to install the required dependencies, otherwise, you can install them manually:
pnpm i -D @eslint-react/eslint-plugin eslint-plugin-react-hooks
If you want to apply lint and auto-fix before every commit, you can add the following to your package.json
:
{
"simple-git-hooks": {
"pre-commit": "pnpm lint-staged"
},
"lint-staged": {
"*": "eslint --fix"
}
}
and then
pnpm i -D lint-staged simple-git-hooks
There is a visual tool to help you view what rules are enabled in your project and apply them to what files, eslint-config-inspector
Go to your project root that contains eslint.config.ts
and run:
npx eslint-config-inspector
Sure, you can configure and override rules locally in your project to fit your needs. If that still does not work for you, you can always fork this repo and maintain your own. I am open to PRs that help improve the overall experience for developers, and there may still be rules activated that do not apply to the roblox-ts ecosystem.