mirror of
https://github.com/scratchfoundation/eslint-config-scratch.git
synced 2025-08-28 22:40:13 -04:00
docs: update README.md with new make{Eslint,Prettier}Config functions
This commit is contained in:
Christopher Willis-Ford
parent
b34628b761
commit
c623bb9236
1 changed files with 133 additions and 52 deletions
185
README.md
185
README.md
|
|
@ -1,85 +1,165 @@
|
|||
# Scratch ESLint config
|
||||
|
||||
`eslint-config-scratch` defines the eslint rules used for Scratch Javascript projects.
|
||||
`eslint-config-scratch` defines `eslint` and `prettier` rules for Scratch Javascript and TypeScript projects.
|
||||
Generally speaking, this configuration uses `prettier` for code style and formatting and `eslint` to flag potential
|
||||
mistakes and encourage code that's easier to read and understand.
|
||||
|
||||
## Installation
|
||||
## Quick Start
|
||||
|
||||
Install the config along with its peer dependencies, eslint and babel-eslint.
|
||||
Install the config along with its peer dependencies, `eslint` and `prettier`:
|
||||
|
||||
```bash
|
||||
npm install -DE eslint-config-scratch eslint@^9 @babel/eslint-parser@^7
|
||||
npm install -D eslint-config-scratch eslint@^9 prettier@^3
|
||||
```
|
||||
|
||||
If you're using the React config, also install the dependency for that
|
||||
Add `eslint.config.mjs` to your project root (pick the `export` line appropriate for your project):
|
||||
|
||||
```bash
|
||||
npm install -DE eslint-plugin-react@^7
|
||||
```js
|
||||
// myProjectRoot/eslint.config.mjs
|
||||
import { makeEslintConfig } from 'eslint-config-scratch'
|
||||
|
||||
// for a TypeScript project:
|
||||
export default makeEslintConfig({ globals: 'browser', tsconfigRootDir: import.meta.dirname })
|
||||
|
||||
// for plain JavaScript:
|
||||
export default makeEslintConfig({ globals: 'browser' })
|
||||
```
|
||||
|
||||
## Usage
|
||||
Add `prettier.config.mjs` to your project root as well:
|
||||
|
||||
TODO: update this section!!!
|
||||
```js
|
||||
// myProjectRoot/prettier.config.mjs
|
||||
import { makePrettierConfig } from 'eslint-config-scratch'
|
||||
|
||||
The configuration is split up into several modules:
|
||||
|
||||
- `eslint-config-scratch`: The base configuration, not configured for any particular environment
|
||||
- `eslint-config-scratch/node`: Rules for targeting Node.js with ESM
|
||||
- `eslint-config-scratch/web`: Rules for targeting Scratch's supported web browsers
|
||||
- `eslint-config-scratch/react`: Rules for targeting Scratch's supported web browsers with React
|
||||
|
||||
These configurations are set up for the flat config format required as of `eslint@^9`.
|
||||
|
||||
Usually web projects contain some files targeting Node.js, for example configuration files, and some targeting web
|
||||
browsers. To lint both with the appropriate rules, set up a base `eslint.config.mjs` with the rules for Node.js and
|
||||
then override that configuration in `src` (or wherever your web code lives).
|
||||
|
||||
Your file structure might look like this:
|
||||
|
||||
```raw
|
||||
scratch-project
|
||||
- eslint.config.mjs
|
||||
- package.json
|
||||
- src
|
||||
- eslint.config.mjs
|
||||
- index.js
|
||||
export default makePrettierConfig()
|
||||
```
|
||||
|
||||
Your config files should be set up like
|
||||
Finally, add scripts like these to your `package.json`:
|
||||
|
||||
```javascript
|
||||
// scratch-project/eslint.config.mjs
|
||||
import nodeConfig from 'eslint-config-scratch/node'
|
||||
|
||||
export default nodeConfig
|
||||
```json
|
||||
"scripts": {
|
||||
"format": "prettier --write . && eslint --fix",
|
||||
"lint": "eslint && prettier --check .",
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// scratch-project/src/eslint.config.mjs
|
||||
import webConfig from 'eslint-config-scratch/web'
|
||||
## Basic Configuration
|
||||
|
||||
The `makeEslintConfig` function takes options to adjust the ESLint configuration object for your project. Most
|
||||
projects should start with something like this:
|
||||
|
||||
```mjs
|
||||
// myProjectRoot/eslint.config.mjs
|
||||
import { makeEslintConfig } from 'eslint-config-scratch'
|
||||
|
||||
export default makeEslintConfig({
|
||||
// Optional: specify global variables available in your environment
|
||||
globals: 'browser',
|
||||
|
||||
// Optional: enables rules that use type info, some of which work in JS too
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
})
|
||||
```
|
||||
|
||||
If you have no `tsconfig.json` (or `jsconfig.json`) in your project, you can skip the `tsconfigRootDir` option. Rules
|
||||
that require type information will be disabled or replaced with less strict alternatives that work without type info.
|
||||
|
||||
### Globals
|
||||
|
||||
The `globals` property is optional. If present, it can take several forms:
|
||||
|
||||
- a string, interpreted as a key in the `globals` object exported by the `globals` package.
|
||||
- Examples: `'browser'`, `'node'`, `'es2021'`, `'jest'`, etc.
|
||||
- an object, set up as described in the "Specifying Globals" section of the [ESLint documentation](https://eslint.org/docs/latest/use/configure/language-options#using-configuration-files)
|
||||
- Example: `{ myGlobal: 'readonly', anotherGlobal: 'writable' }`
|
||||
- an array of zero or more of any mixture of the above
|
||||
|
||||
```mjs
|
||||
// myProjectRoot/eslint.config.mjs
|
||||
import { makeEslintConfig } from 'eslint-config-scratch'
|
||||
|
||||
export default makeEslintConfig({
|
||||
// Optional: enables rules that use type info, some of which work in JS too
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
|
||||
// Optional: specify global variables available in your environment
|
||||
// Warning: this is a very silly configuration
|
||||
globals: [
|
||||
'shared-node-browser',
|
||||
{
|
||||
fun: 'readonly',
|
||||
thing: false,
|
||||
},
|
||||
'es2021',
|
||||
{
|
||||
whyNot: 'writable',
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### Further Customization
|
||||
|
||||
The return value of the `makeEslintConfig` function is a standard ESLint configuration array. This means you can
|
||||
customize your configuration further like this:
|
||||
|
||||
```mjs
|
||||
// myProjectRoot/eslint.config.mjs
|
||||
import { makeEslintConfig } from 'eslint-config-scratch'
|
||||
|
||||
export default [
|
||||
webConfig,
|
||||
// If you need to add or override settings:
|
||||
...makeEslintConfig({
|
||||
// Optional: enables rules that use type info, some of which work in JS too
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
|
||||
// Optional: specify global variables available in your environment
|
||||
globals: 'browser',
|
||||
}),
|
||||
// Add custom rules or overrides here
|
||||
{
|
||||
files: ['*.test.js'],
|
||||
rules: {
|
||||
// ...
|
||||
'no-console': 'off', // Allow console logs in test files
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
This will set up all the files in the project for linting as Node.js by default,
|
||||
except for those in `src/`, which will be linted as ES6 and React files.
|
||||
All ESLint configuration options are available this way. You can use this to handle globals yourself if the simplified
|
||||
`globals` configuration from above doesn't meet your needs:
|
||||
|
||||
In most cases, you won't need to specify the file names or extensions that `eslint` should check. You can probably
|
||||
just use this:
|
||||
```mjs
|
||||
// myProjectRoot/eslint.config.mjs
|
||||
import { makeEslintConfig } from 'eslint-config-scratch'
|
||||
import globals from 'globals'
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"lint": "eslint"
|
||||
}
|
||||
export default [
|
||||
...makeEslintConfig({
|
||||
// Optional: enables rules that use type info, some of which work in JS too
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
}),
|
||||
{
|
||||
files: ['src/main/**.js'],
|
||||
languageOptions: {
|
||||
globals: globals.node,
|
||||
},
|
||||
},
|
||||
{
|
||||
files: ['src/renderer/**.js'],
|
||||
languageOptions: {
|
||||
globals: {
|
||||
...globals.browser,
|
||||
MY_CUSTOM_GLOBAL: 'readonly',
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
Of course, another option would be to place a different `eslint.config.mjs` file in each subdirectory. If you have
|
||||
multiple `tsconfig.json` or `jsconfig.json` files in your project, it likely makes sense to have an
|
||||
`eslint.config.mjs` file beside each one.
|
||||
|
||||
## Legacy Styles
|
||||
|
||||
Scratch used very different styling rules in `eslint-config-scratch@^9` and below. If you need to use those rules, you
|
||||
|
|
@ -90,7 +170,8 @@ can use the rule sets under `legacy/`:
|
|||
- `eslint-config-scratch/legacy/node`: Legacy rules for targeting Node.js
|
||||
- `eslint-config-scratch/legacy/react`: Legacy rules for targeting Scratch's supported web browsers with React
|
||||
|
||||
New projects should not use these rule sets. They may disappear in the future.
|
||||
New projects should not use these rule sets. They may disappear in the future. Scratch did not use Prettier at this
|
||||
time, so there is no legacy Prettier configuration.
|
||||
|
||||
## Committing
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue