Granular configuration per language/files

[ematipico]

Description

Now that Biome has started to support multiple languages, we should be able to control better how those languages behave inside the internal tools.

For example, people might want to format JavaScript files with tabs, but JSON files with spaces. At the moment, this isn't possible via configuration.

Goals

• Provide a way to manipulate the behaviour of tools based on languages and files.
• Use an existing pattern already used in the ecosystem, slightly adapted to Biome.
• Progressively provide these new enhancements without breaking the existing configuration, if possible.

Specifics

Formatter

Below are some examples of how we could better control the formatter:

Enable the tool via language

{
	"javascript": {
		"formatter": {
			"enabled": true
		}
	},
	"json": {
		"formatter": {
			"enabled": false,
		}
	}
}

In this example, JavaScript files are regularly formatted, while JSON files aren't.

Inside "formatter", we will have the same options contained in the top-level formatter property

Change options via language

{
	"formatter": {
		"indentStyle": "tab"
	},
	"json": {
		"formatter": {
			"indentStyle": "space",
			"lineWidth": 100
		}
	}
}

We format JSON files with a different indentation style and line width in this example.

Inside "formatter", we will have the same options contained in the top-level formatter property

Change language behaviour based on files

A new field, called overrides. This field already has some prior work in the ecosystem, such as Prettier and ESLint. However, Biome will use them slightly differently because we already distinguish the languages at the configuration level.

{
	"formatter": {
		"indentStyle": "tab"
	},
	"javascript": {
		"overrides": [
			{
				"files": ["*.d.ts"],
				"formatter": {
					"enabled": false,
				}
			},
			{
				"files": ["generated/**"],
				"formatter": {
					"indentStyle": "tab",
					"quoteStyle": "double"
				}
			},
		]
	},
	"json": {
		"formatter": {
			"indentStyle": "space",
			"lineWidth": 100
		}
	}
}

• overrides is a configuration present right after the language key;
• overrides is an array that contains the following object

{
	"files": [],
	"formatter": {}
}

We can tinker with the tool based on the files specified in files. files is an array of Unix-like patterns. If we match a file under these patterns, Biome will apply the configuration specified here.

From the previous example:

{
	"files": ["*.d.ts"],
	"formatter": {
		"enabled": false,
	}
}

The formatter won't be executed fir .d.ts files.

The second example is particular. Inside "formatter" will have "base" options such as indentStyle and tabWith, and language-specific options like quoteStyle.

{
	{
		"files": ["generated/**"],
		"formatter": {
			"indentStyle": "tab",
			"quoteStyle": "double"
		}
	},
}

Here, JavaScript files under a generated/ directory will be formatted using tabs with a double quote style.

Linter

Enable the tool via language

Below are some examples of how we could better control the linter:

{
	"javascript": {
		"linter": {
			"enabled": true
		}
	},
	"json": {
		"linter": {
			"enabled": false,
		}
	}
}

JavaScript files are regularly linted in this example, while JSON files aren't.

Tinker rules based on files

{
	"linter": {
		"enabled": true,
		"rules": {
			"recommended": true
		}
	},
	"javascript": {
		"overrides": [
			{
				"files": ["generated/**"],
				"linter": {
					"rules": {
						"all": false,
						"performance": {
							"noDelete": "error"
						}
					}
				}
			},
			{
				"files": ["external/**"],
				"linter": {
					"enabled": false
				}
			}
		]
	}
}

In this example:

• We tell Biome that JavaScript files under the generated/ directory should have all the rules turned off, exception for noDelete.
• We tell Biome to not lint JavaScript files under the external/** directory.

[Vivalldi]

Overall I'm in favor of this proposal. I would like to propose 2 adjustments

Adjustment 1

All tool overrides belong in the tool field and not the language field.

Motivation
The current biome config has language (eg: javascript) & tool (eg linter) specific fields at the root level. When I want to modify linter rules the natural spot is the linter field.

Example

{
    "linter": {
        "enabled": true,
        "rules": {
            "recommended": true
        },
        "overrides": [
            {
                "javascript": {
                    "rules": {
                        "all": false,
                        "performance": {
                            "noDelete": "error"
                        }
                    }
                }
            },
            {
                "json": {
                    "enabled": false
                }
            }
        ]
    }
}

This has the following impact:

• We tell Biome that all javascript files should have all the rules turned off, exception for noDelete.
• We tell Biome to not lint on all json files.

Adjustment 2

Use "collapsed" keys to pattern match overrides (similar to vscode language specific overrides)

• {file path}: Keys with curly braces {} match a file path
• [language]: Keys with square brackets [] match a language (as defined by biome)

Motivation
IMO this makes overrides easier to grok as they're much closer to the original definition. Initially this can be used at specific levels (directly below linter or javascript) but could easily be expanded to allow field specific overrides.

Example

{
    "linter": {
        "enabled": true,
        "[json]": {
            "enabled": false
        },
        "{generated/**}": {
            "rules": {
                "all": false,
                "performance": {
                    "noDelete": "error"
                }
            }
        }
    }
}

This has the following impact:

• We tell Biome to not lint on all json files.
• We tell Biome that all files under the generated/ directory should have all the rules turned off, exception for noDelete.

[ematipico]

IMO this makes overrides easier to grok as they're much closer to the original definition

Do you have some sources that speak about the "original definition"?

Use "collapsed" keys to pattern match overrides (similar to vscode language specific overrides)

{file path}: Keys with curly braces {} match a file path
[language]: Keys with square brackets [] match a language (as defined by biome)

These keys might not be very friendly; here are some reasons why:

• This configuration is hard to represent in our Rust. We can parse them using our parser, but these types still need to be sent over the wire using our Daemon, and we rely on serde to do that; also, we generate JSON schema from this configuration, we may lose some auto-completion.
• It requires a mini parser for these keys. E.g. "[json" should throw a reasonable error. How do other tools behave with such grammar?
• Users need to know beforehand how [] and {} work. This require a well written documentation, even inside the JSON schema - if we can represent it.

I see that your suggestion provides a bit more flat structure, though.

[Conaclos]

I think we could adopt a simpler format: delimiter-seperated patterns.
For example with spaces:

...
"src/**/*.ts test/**/*.js": {}
...

Or pipes:

...
"src/**/*.ts|test/**/*.js": {}
...

[Vivalldi]

Do you have some sources that speak about the "original definition"?

By this I meant it's closer to the original config location, as in overrides are right next to the fields they're overriding.

These keys might not be very friendly

I agree with all your points. As a "halfway" point for flattening we could keep the overrides key but use object keys instead of an array.

{
    "linter": {
        "enabled": true,
        "overrides": {
            "json": {
                "enabled": false
            },
            "generated/**": {
                "rules": {
                    "all": false,
                    "performance": {
                        "noDelete": "error"
                    }
                }
            }
        }
    }
}

Unsure how we would easily differentiate between languages & filepaths.

[nstepien]

A few thoughts:

• Instead of "files": [...] only, can we consider using include/exclude? like rollup configs/plugins
• Can/should we be able to specify multiple languages at once? VSCode allows it with this syntax
• Would all this work well with embedded languages?
• Can overrides be specified as a top-level config as well? Or must it be nested under a language? i.e. can we do this?

  {
    "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
    "linter": {
      // default config to apply to all files
    },
    "overrides": {
      "include": ["./src/**/*.test.*"],
      "linter": {
        // apply specific rules to test files only
      }
    }
  }

[ematipico]

I think you're onto something here! I like the top-level overrides and the include/exclude thing. The include/exclude will play very well with the formatter, which is already designed to exclude or include lint rules.

[arendjr]

Sorry I’m late to the party here, but for me it’s important to be able to replicate the functionality that ESLint offers by nesting .eslintrc files in subdirectories (which is: apply additional rules or lift some restrictions within specific subdirectories). Biome doesn’t appear to like nested biome.json files as much, because even though the extends functionality gets you partially there, it requires running Biome from the innermost subdirectory. I.e. if you run Biome from a directory with a “root” biome.json, it doesn’t pick up nested biome.json files to be applied to subdirectories only.

That said, I think @nstepien’s top-level overrides suggestion with include fields provides all the functionality I need and I like you can still keep everything together in one file that way.

[ematipico]

Umbrella issue created #491