Skip to content

Commit

Permalink
update all documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@bsokol-wl
bsokol-wl committed May 10, 2024
1 parent 2dab2ae commit fd7f027
Show file tree
Hide file tree
Showing 5 changed files with 305 additions and 197 deletions.
77 changes: 44 additions & 33 deletions docs/eslint/advanced-composition.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,50 +33,61 @@ Each configuration piece can be extended individually, or in combination with ot

To extend the configuration with a single piece:

```json !#4 .eslintrc.json
{
"$schema": "https://json.schemastore.org/eslintrc",
"root": true,
"extends": "plugin:@workleap/typescript",
"rules": {
...
}
}
```javascript !#4 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
...workleapPlugin.configs.typescript
];

export default config;
```

### Multiple pieces

To extend the configuration with multiple pieces:

```json !#4 .eslintrc.json
{
"$schema": "https://json.schemastore.org/eslintrc",
"root": true,
"extends": ["plugin:@workleap/core", "plugin:@workleap/typescript"],
"rules": {
...
}
}
```javascript !#4-5 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
...workleapPlugin.configs.core,
...workleapPlugin.configs.typescript,
];

export default config;
```

## Lint additional files
The `concat` helper from [eslint-flat-config-utils](https://github.com/antfu/eslint-flat-config-utils) is useful to avoid having to spread arrays.

```javascript !#1,4-7 eslint.config.js
import { concat } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";

const config = concat(
workleapPlugin.configs.core,
workleapPlugin.configs.typescript,
);

The configuration pieces already targets which file extensions their linting rules will be applied to. If you wish to lint additional file extensions for a given piece you can add an ESLint [override block](https://eslint.org/docs/latest/use/configure/configuration-files#how-do-overrides-work):

```json !#5-10 .eslintrc.json
{
"$schema": "https://json.schemastore.org/eslintrc",
"root": true,
"extends": ["plugin:@workleap/react"],
"overrides": [
{
"files": ["*.js", "*.jsx"],
"extends": "plugin:@workleap/react"
}
]
}
export default config;
```

## Lint additional files

The configuration pieces already target which file extensions their linting rules will be applied to. If you wish to lint additional file extensions for a given piece you can override the `files` key as you would with any JavaScript object. Since Workleap shared configs are arrays, you will need to use a `map` function.

```javascript !#4-7 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
...workleapPlugin.configs.react.map(conf => ({
...conf,
files: ["*.js", "*.jsx"],
}))
];

export default config;
```



Expand Down
109 changes: 76 additions & 33 deletions docs/eslint/custom-configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,45 +16,57 @@ For a list of the rules included with the default shared configurations, refer t

You can disable a default rule by defining the rule locally with the `"off"` value:

```json !#5-7 .eslintrc.json
{
"$schema": "https://json.schemastore.org/eslintrc",
"root": true,
"extends": "plugin:@workleap/web-application",
"rules": {
"no-var": "off"
```javascript !#5-9 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
...workleapPlugin.configs.webApplication,
{
rules: {
"no-var": "off"
}
}
}
];

export default config;
```

## Change a default rule severity

You can update the severity of a rule by defining the rule locally with either the `"warn"` or `"error"` severity:

```json !#5-7 .eslintrc.json
{
"$schema": "https://json.schemastore.org/eslintrc",
"root": true,
"extends": "plugin:@workleap/web-application",
"rules": {
"jsx-a11y/alt-text": "error"
```javascript !#5-9 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
...workleapPlugin.configs.webApplication,
{
rules: {
"jsx-a11y/alt-text": "error"
}
}
}
];

export default config;
```

## Change a default rule value

You can update a default rule value by defining the rule locally with its new value:

```json !#5-7 .eslintrc.json
{
"$schema": "https://json.schemastore.org/eslintrc",
"root": true,
"extends": "plugin:@workleap/web-application",
"rules": {
"quotes": ["warn", "single"]
```javascript !#5-9 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
...workleapPlugin.configs.webApplication,
{
rules: {
"quotes": ["warn", "single"]
}
}
}
];

export default config;
```

!!!light
Expand All @@ -65,16 +77,47 @@ Please, don't update your project configuration to use single quotes :sweat_smil

You can add configure additional rules from a third party [ESLint plugin](https://eslint.org/docs/latest/use/configure/plugins):

```json !#4,6-8 .eslintrc.json
{
"$schema": "https://json.schemastore.org/eslintrc",
"root": true,
"plugins": ["unicorn"],
"extends": "plugin:@workleap/web-application",
"rules": {
"unicorn/better-regex": "error"
```javascript !#2,6-13 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";
import eslintPluginUnicorn from 'eslint-plugin-unicorn';

const config = [
...workleapPlugin.configs.webApplication,
{
plugins: {
unicorn: eslintPluginUnicorn,
},
rules: {
"unicorn/better-regex": "error"
}
}
}
];

export default config;
```

## `concat` helper

If you are combining many configuration objects, it can be helpful to use the `concat` helper from [eslint-flat-config-utils](https://github.com/antfu/eslint-flat-config-utils) to avoid having to spread arrays.

```javascript !#1,5,15 eslint.config.js
import { concat } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";
import eslintPluginUnicorn from 'eslint-plugin-unicorn';

const config = concat(
workleapPlugin.configs.webApplication,
{
plugins: {
unicorn: eslintPluginUnicorn,
},
rules: {
"unicorn/better-regex": "error"
}
}
);

export default config;
```

## Start from scratch
Expand Down
46 changes: 22 additions & 24 deletions docs/eslint/flat-config-migration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Create a file called `eslint.config.js`. `@workleap/eslint-config` is published
### Initial setup

Import the `@workleap/eslint-config` module. Create a config array and set it as the default export.
```javascript
```javascript !#3-5 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
Expand All @@ -40,7 +40,7 @@ export default config;

ESLint will no longer use the `.eslintignore` file. If you have one of these files, create a new configuration object with an `ignores` key:

```javascript
```javascript !#4-6 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
Expand All @@ -54,19 +54,12 @@ export default config;

## Recommended setup - By project type

`@workleap/eslint-config` exposes some pre-built configs based on common project types. Each of these configs are properly set up for **JavaScript**, **TypeScript**, **Jest**, **Testing Library**, **MDX**, and **package.json**.
`@workleap/eslint-config` exposes some pre-built configs based on common project types. Each of these configs are properly set up for **JavaScript**, **TypeScript**, **Jest**, **Testing Library**, **MDX**, and **package.json**. Some configs will additionally lint **React**, **JSX A11y**, and **Storybook**. See [available configurations](../eslint/#available-configurations).

By convention, all configs are found at `workleapPlugin.configs`. A flat config can be a single object or an array, but for simplicity, all Workleap configs are exported as arrays. Therefore, each Workleap config must be spread (`...`) into the config array.

| Type | Config Key | Purpose | Additional Configs |
|---|---|---|---|
| Web Application | `configs.webApplication` | General purpose web application using React and TypeScript | React<br>JSX A11y<br>Storybook |
| TypeScript Library | `configs.typeScriptLibrary` | For building a TypeScript library to be consumed by another project | |
| React Library | `configs.reactLibrary` | For building a React library to be consumed by another project | React<br>JSX A11y<br>Storybook |
| Monorepo Workspace | `configs.monorepoWorkspace` | For the top level of a monorepo | |

For example, to configure ESLint for a React web application, add the project config to your config array:
```javascript
```javascript !#7 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = [
Expand All @@ -79,10 +72,15 @@ const config = [
export default config;
```

In order to make it easier to combine config files, we recommend using [eslint-flat-config-utils](https://github.com/antfu/eslint-flat-config-utils). Wrap your configuration objects in the `concat` function to automatically combine and flatten arrays of configs. This returns a promise, which you can `await` before exporting.
In order to make it easier to combine config files, we recommend using [eslint-flat-config-utils](https://github.com/antfu/eslint-flat-config-utils). Wrap your configuration objects in the `concat` function to automatically combine and flatten arrays of configs. This returns a promise, which you can `await` before exporting.

!!!Info
Awaiting this promise is not necessary if this is a top level config file. If this is in a monorepo package ([see below](#monorepo-packages)), then you can handle the promise automatically by using `concat` in the top level config file.
!!!

You can override individual rules across all configs by adding another configuration object to the array:
```javascript
```javascript !#1,4,9-13,14 eslint.config.js
import { concat } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";

const config = await concat(
Expand Down Expand Up @@ -111,7 +109,7 @@ We can mimic the old ESLint behavior by importing each package's ESLint config i
### Monorepo packages

Inside each monorepo package, create a `eslint.config.js` file. Add the config module that matches the package type. For example, a web application would use the `webApplication` config, while a component libary would use the `reactLibrary` config:
```javascript
```javascript !#4 eslint.config.js
import workleapPlugin from "@workleap/eslint-config";

const config = {
Expand All @@ -122,11 +120,11 @@ export default config;
```

You can also set custom ignore rules:
```javascript
```javascript !#6 eslint.config.js
import { concat } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";

const config = await concat(
const config = concat(
workleapPlugin.configs.reactLibrary,
ignores: ["build/"]
);
Expand All @@ -138,11 +136,11 @@ export default config;

Create a new `eslint.config.js` at the root of your project. Import the monorepo workspace config.

```javascript
```javascript !#8 eslint.config.js
import { concat } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";

const config = await concat(
const config = concat(
{
ignores: ["node_modules/"]
},
Expand All @@ -154,13 +152,13 @@ export default config;

Import each package's `eslint.config.js` and add them to the `concat` function. Wrap each of the package imports with the `extend` function, and provide the relative path to the root of each package. This will scope the files of that config to the given directory, including any ignores.

```javascript
```javascript !#1,3-4,11-12 eslint.config.js
import { concat, extend } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";
import packageOneConfig from "./packages/one";
import packageTwoConfig from "./packages/two";

const config = await concat(
const config = concat(
{
ignores: ["node_modules/"]
},
Expand All @@ -178,11 +176,11 @@ With this setup, you can lint the entire project from the root, or from within e

We recommend using one of the "by project type" configurations for simplicity and consistency. But if you need to customize further, you can choose to combine [any individual configs](advanced-composition). Here, we'll compose a config for a project that uses React and TypeScript.

```javascript
```javascript !#5-7 eslint.config.js
import { concat } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";

const config = await concat(
const config = concat(
workleapPlugin.configs.core,
workleapPlugin.configs.typescript,
workleadPlugin.configs.react
Expand All @@ -192,11 +190,11 @@ export default config;
```

Some rules may need to be overridden within each nested config object. Since flat configs are entirely JavaScript, we can manipulate the underlying configuration objects directly. For example, to change the file type used by a config object:
```javascript
```javascript !#7-12 eslint.config.js
import { concat } from "eslint-flat-config-utils";
import workleapPlugin from "@workleap/eslint-config";

const config = await concat(
const config = concat(
workleapPlugin.configs.core,
workleapPlugin.configs.typescript,
workleadPlugin.configs.react.map(conf => (
Expand Down
Loading

0 comments on commit fd7f027

Please sign in to comment.