diff --git a/astro.config.ts b/astro.config.ts index 4182a8828..b84de28e2 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -78,6 +78,15 @@ export default defineConfig({ "pt-BR": "Instalação manual", }, }, + { + label: "Configure Biome", + link: "/guides/configure-biome", + translations: { + ja: "バイオームの設定", + "zh-CN": "配置生物群落", + "pt-BR": "Configurar Bioma", + }, + }, { label: "Use Biome in big projects", link: "/guides/big-projects", @@ -87,15 +96,6 @@ export default defineConfig({ "pt-BR": "Usando o Biome em projetos grandes", }, }, - { - label: "How Biome works", - link: "/guides/how-biome-works", - translations: { - ja: "Biome の振る舞い", - "zh-CN": "Biome 工作原理", - "pt-BR": "Como o Biome funciona", - }, - }, { label: "Biome in your IDE", translations: { diff --git a/src/content/blog/biome-v1-7.md b/src/content/blog/biome-v1-7.md index 4e6a6f031..0dc1b1d1d 100644 --- a/src/content/blog/biome-v1-7.md +++ b/src/content/blog/biome-v1-7.md @@ -279,7 +279,7 @@ The following rules are promoted: - You can now ignore `React` imports in the rules [noUnusedImports](/linter/rules/no-unused-imports/#options) and [useImportType](/linter/rules/use-import-type/#options) by setting [`javascript.jsxRuntime`](/reference/configuration/#javascriptjsxruntime) to `reactClassic`. -- Biome applies specific settings to [well-known files](/guides/how-biome-works/#well-known-files). +- Biome applies specific settings to [well-known files](/guides/configure-biome/#well-known-files). It now recognizes more files and distinguishes between JSON files that only allow comments and JSON files that allow both comments and trailing commas. - In the React ecosystem, files ending in `.js` are allowed to contain JSX syntax. diff --git a/src/content/docs/formatter/index.mdx b/src/content/docs/formatter/index.mdx index d94226adb..b5b574ce7 100644 --- a/src/content/docs/formatter/index.mdx +++ b/src/content/docs/formatter/index.mdx @@ -44,10 +44,10 @@ For more information about all the available options, check the [CLI reference]( Biome provides some options to tune the behavior of its formatter. Differently from other tools, Biome separates language-agnostic options from language-specific options. -The formatter options can be set on the [CLI](/reference/cli/#biome-format) or via a [Biome configuration file](/guides/how-biome-works/#configuration). +The formatter options can be set on the [CLI](/reference/cli/#biome-format) or via a [Biome configuration file](/guides/configure-biome). Biome doesn't support `.editorconfig` [yet](https://github.com/biomejs/biome/issues/1724). -It's recommended to use a [Biome configuration file](/guides/how-biome-works#configuration) to ensure that both the Biome CLI and the Biome LSP apply the same options. +It's recommended to use a [Biome configuration file](/guides/configure-biome) to ensure that both the Biome CLI and the Biome LSP apply the same options. The following defaults are applied: ```json title="biome.json" @@ -90,7 +90,7 @@ The main language-agnostic options supported by the Biome formatter are: See the [configuration reference](/reference/configuration#formatter) for more details. -## Ignoring Code +## Ignore Code There are times when the formatted code isn't ideal. @@ -125,29 +125,5 @@ const expr = ]; ``` - -## Ignoring files - Biome doesn't provide ignore comments that ignore an entire file. -However, you can ignore a file using the Biome configuration file. - -You can ignore files for all tools, including the formatter, -using the [`files.ignore` configuration](/guides/how-biome-works#include-and-ignore-explained). -By default, Biome ignores the [protected files](/guides/how-biome-works#protected-files). - -If you want to exclude files from being formatted, you can use `formatter.ignore`: - -```json title="biome.jsonc" -{ - "files": { - // All tools, including the formatter, ignore following files - "ignore": ["dist/**"] - }, - "formatter": { - // Only the formatter ignores the following files - "ignore": ["test/**"] - } -} -``` - -Note that you can also [ignore files ignored by your VCS](/guides/integrate-in-vcs#use-the-ignore-file). +However, you can [ignore a file using the Biome configuration file](/guides/configure-biome/#ignore-files). diff --git a/src/content/docs/guides/big-projects.mdx b/src/content/docs/guides/big-projects.mdx index 0da479379..33eb1e5dd 100644 --- a/src/content/docs/guides/big-projects.mdx +++ b/src/content/docs/guides/big-projects.mdx @@ -38,7 +38,7 @@ When you run a script from `app/frontend/legacy-app/package.json` or `app/fronte ## Share the configuration -It's possible to use the [`extends`](/guides/how-biome-works/#the-extends-option) configuration option to breakdown options across files. +It's possible to use the [`extends`](/guides/configure-biome/#share-a-configuration-file) configuration option to breakdown options across files. Let's assume that we have these requirements: - `legacy-app` have to format using spaces; diff --git a/src/content/docs/guides/configure-biome.mdx b/src/content/docs/guides/configure-biome.mdx new file mode 100644 index 000000000..149ec620d --- /dev/null +++ b/src/content/docs/guides/configure-biome.mdx @@ -0,0 +1,387 @@ +--- +title: Configure Biome +description: Learn how Biome configuration works. +--- + +import {FileTree} from '@astrojs/starlight/components'; + +This guide will help you to understand how to configure Biome. +It explains the structure of a Biome configuration file and how Biome resolves its configuration. +If you are already familiar with the configuration, you may want to take a look at the [configuration reference](/reference/configuration/), which details all the options available. + +Biome allows you to customize its behavior using CLI options or a configuration file named `biome.json` or `biome.jsonc`. +We recommend that you create a configuration file for each project. +This ensures that each team member has the same configuration in the CLI and in any editor that allows Biome integration. +Many of the options available in a configuration file are also available in the CLI. + +## Configuration file structure + +A Biome configuration file is named `biome.json` or `biome.jsonc`. +It is usually placed in your project's root directory, next to your project's `package.json`. + +Because Biome is a toolchain, its configuration is organized around the tools it provides. +At the moment, Biome provides three tools: the formatter, the linter and the import sorter (also called the import organizer). +All of these tools are enabled by default. +You can disable one or several of them using the `.enabled` field: + +```json title="biome.json" +{ + "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json", + "formatter": { + "enabled": false + }, + "linter": { + "enabled": false + }, + "organizeImports": { + "enabled": false + } +} +``` + +Options that apply to more than one language are placed in the corresponding tool field. +Language-specific options of a tool are placed under a `.` field. +This also allows overriding general options for a given language. +You can also enable or disable a tool based on the language. +In the following example, we configure the general options `formatter.indentStyle` and `formatter.lineWidth` for all the languages. +Also, we set the JavaScript-specific option `quoteStyle` in `javascript.formatter` and we override `formatter.lineWidth`. +We disabled the formatter for JSON files. + +```json5 title="biome.jsonc" +{ + "formatter": { + "indentStyle": "space", // default is `tab` + "lineWidth": 100 // default is `80` + }, + "javascript": { + "formatter": { + "quoteStyle": "single", // default is `double` + "lineWidth": 120 // override `formatter.lineWidth` + } + }, + "json": { + "formatter": { + "enabled": false + } + } +} +``` + +:::note +Biome refers as `javascript` all variants of the JavaScript language. +This includes TypeScrip, JSX and TSX. +::: + + +## Configuration file resolution + +Biome uses auto discovery to find the nearest configuration file. +It looks in the working directory and in the parent directories until it finds a `biome.json` or a `biome.jsonc` file. +If no configuration is found, then it applies Biome's defaults. +If both `biome.json` and `biome.jsonc` are present in the same folder, the priority will be given to `biome.json`. + +Here's an example: + + +- app + - backend + - biome.json + - package.json + - frontend + - biome.json + - legacy + - package.json + - new + - package.json + + + +- Biome commands that run in `app/backend/package.json` will use the configuration file `app/backend/biome.json`; +- Biome commands that run in `app/frontend/legacy/package.json` and `app/frontend/new/package.json` +will use the configuration file `app/frontend/biome.json`; + +:::caution +Biome doesn't support nested `biome.json` files, neither in CLI nor in LSP. [Follow and help the support in the related issue](https://github.com/biomejs/biome/issues/2228) +::: + +:::note +Biome commands support using the `--config-path` option and the `BIOME_CONFIG_PATH` environment variable. +This allows you to specify a custom configuration file or a directory where Biome can look for a `biome.json` or `biome.jsonc` file. +When you use `--config-path` or `BIOME_CONFIG_PATH`, the standard configuration file resolution process is **disabled**. + +If `--config-path` or `BIOME_CONFIG_PATH` points directly to a file, you can use names other than `biome.json` or `biome.jsonc`. +Biome will read a `.json` file using a standard JSON parser. +For files with other extensions, Biome will treat them as `.jsonc` files, using a more flexible JSON parser that allows comments and trailing commas. +::: + + +## Share a configuration file + +The `extends` field allows you to split your configuration across multiple files. +This way, you can share common settings across different projects or folders. + +Here's an example of how you might set up your configuration to extend a `common.json` configuration file: + +```json title="biome.json" +{ + "extends": ["./common.json"] +} +``` + +The entries defined in `extends` are resolved from the path where the `biome.json` file is defined. +They are processed in the order they are listed, with settings in later files overriding earlier ones. + +Biome is able to resolve configuration files from the `node_modules/` directory. +So you can export your configuration file from a package, and import it in multiple projects. + +In order to do so, the first thing to do is to set up your "shared" Biome configuration in a certain way. +Let's suppose that you want to share a configuration from a package called `@org/shared-configs`, using the specifier `@org/shared-configs/biome`. +You have to create an `exports` entry in the `package.json` of this package: + +```json title="package.json" ins={5,3} +{ + "name": "@org/shared-configs", + "type": "module", + "exports": { + "./biome": "./biome.json" + } +} +``` + +Make sure that `@org/shared-configs` is correctly installed in your project, and update the `biome.json` file to look like the following snippet: + +```json title="biome.json" +{ + "extends": ["@org/shared-configs/biome"] +} +``` + +Biome will attempt to **resolve** your library `@org/shared-configs/` from your working directory. +The working directory is: + +- when using the CLI, the directory where you execute your scripts from. + Usually it matches the location of your `package.json` file; +- when using the LSP, the root directory of your project. + +:::caution +To avoid a breaking change with how the existing resolution works, paths starting with a dot `.` or ending with `.json` or `.jsonc` **won't** be resolved from `node_modules/`. +::: + +For more information about the resolution algorithm, refer to the [Node.js documentation](https://nodejs.org/api/esm.html#resolution-and-loading-algorithm). + + +## Ignore files + +The first way to control which files and directories are processed by Biome is to list them in the CLI. +In the following command, we format only `file1.js` and all the files in the `src` directory. +The directories are recursively traversed. + +```shell +biome format file1.js src/ +``` + +:::caution +Glob patterns used on the command line are not interpreted by Biome. +They are expanded by your shell. +Some shells don't support the recursive glob `**`. +::: + +The Biome configuration file can be used to refine which files are processed. +You can explicitly list the files to be processed using `include` and the files not to be processed using `ignore`. +`include` and `ignore` accepts globs patterns such as `src/**/*.js`. +See the [related section](#glob-syntax-explained) for which glob syntaxes are supported. +`include` is always applied first before applying `ignore`. +This allows you to include some files and to ignore some of the file you included. + +:::note +`include` and `ignore` have a slightly different semantics. +`include` doesn't prevent Biome of traversing a folder. +This means that if you want to prevent Biome from traversing a folder, you have to add the folder to `ignore`. +::: + +Biome provides global `files.include` and `files.ignore` fields that apply to all tools. +You can also include and ignore files at tool level using `.include` and `.ignore`. +Note that they don't override the global `files.include` and `files.ignore`. +`files.include` and `files.ignore` are applied first before a tool's `include` and `ignore`. + +Let's take the following configuration: + +```json title="biome.json" +{ + "files": { + "include": ["src/**.js", "test/**.js"], + "ignore": ["**/*.min.js"], + }, + "linter": { + "ignore": ["test"] + } +} +``` + +And run the following command: + +```shell +biome format test/ +``` + +The command will format the files that end with the `.js` extension and doesn't end with the `.min.js` extension from the `test` directory. +The files in `src` are not formatted because the directory is not listed in the CLI. + +If we run the following command, no files are linted because the `test` directory is explicitly ignored for the linter. + +```shell +biome lint test/ +``` + +Biome resolves the globs relatively from the working directory. +The working directory is the directory where you usually run a CLI command. +This means that you have to place **particular attention** when the configuration file is placed in +a different directory from where you execute your command. +In the case of an editor (LSP) the working directory is the root directory of your project. + +Let's take a project that contains two directories `backend/` and `frontend/`, and the Biome configuration file that we introduced earlier. +Inside the `frontend/` directory, a `package.json` specifies a `format` script that runs the Biome formatter. + + +- backend + - ... +- biome.json +- frontend + - package.json + - src + - ... + - test + - ... + + +```json title="frontend/package.json" +{ + "name": "frontend-project", + "scripts": { + "format": "biome format --write ./" + } +} +``` + +When you run the script `format` from `frontend/package.json`, +the working directory resolved by that script will be `frontend/`. +The globs `src/**/*.js` and `test/**/*.js` will have as "base" directory `frontend/`. +Thus, only the files from `frontend/src/` and `frontend/test/` will be formatted. + +```json title="biome.json" +{ + "files": { + "include": ["src/**/*.js", "src/**/*.ts"], + "ignore": ["test"] + }, + "formatter": { + "indentStyle": "space" + } +} +``` + +:::caution +`ignore` and `include` inside `overrides` have a **different** semantics: +- for `ignore`: if a file matches the globs, **_don't_ apply** the configuration inside this override, and keep apply the next overrides; +- for `include`: if a file matches the globs, **apply** the configuration inside this override, and keep apply the next overrides; +::: + +:::note +By default, Biome always ignores some files that are said to be **protected files**. +This means that no diagnostics will be ever emitted by Biome for those files. +At the moment, the following files are protected: + +- `composer.lock` +- `npm-shrinkwrap.json` +- `package-lock.json` +- `yarn.lock` +::: + +:::note +You can also [ignore files ignored by your VCS](/guides/integrate-in-vcs#use-the-ignore-file). +::: + + +## Well-known files + +Here are some well-known files that we specifically treat based on their file names, rather than their extensions. +Currently, the well-known files are JSON-like files only, but we may broaden the list to include other types when we support new parsers. + +The following files are parsed as `JSON` files with both the options `json.parser.allowComments` and `json.parser.allowTrailingCommas` set to `false`. + +- `.all-contributorsrc` +- `.arcconfig` +- `.auto-changelog` +- `.bowerrc` +- `.c8rc` +- `.htmlhintrc` +- `.imgbotconfig` +- `.jslintrc` +- `.nycrc` +- `.tern-config` +- `.tern-project` +- `.vuerc` +- `.watchmanconfig` +- `mcmod.info` + +The following files are parsed as `JSON` files with the options `json.parser.allowComments` set to `true` but `json.parser.allowTrailingCommas` set to `false`. This is because the tools consuming these files can only strip comments. + +- `.ember-cli` +- `.eslintrc.json` +- `.jscsrc` +- `.jshintrc` +- `tslint.json` + +The following files are parsed as `JSON` files with the options `json.parser.allowComments` and `json.parser.allowTrailingCommas` set to `true`. This is because the tools consuming these files are designed to accommodate such settings. + +- `.babelrc` +- `.babelrc.json` +- `.devcontainer.json` +- `.hintrc` +- `.hintrc.json` +- `.swcrc` +- `api-documenter.json` +- `api-extractor.json` +- `babel.config.json` +- `deno.json` +- `devcontainer.json` +- `dprint.json` +- `jsconfig.json` +- `jsr.json` +- `language-configuration.json` +- `tsconfig.json` +- `typedoc.json` +- `typescript.json` + + +## Glob syntax explained + +A glob pattern specifies a set of filenames. +Biome supports the following globs: + +- `*` matches zero or more characters. It cannot match the path separator `/`. +- `**` recursively matches directories and files. + This sequence **must** form a single path component, + so both `**a` and `b**` are invalid and will result in an error. + A sequence of more than two consecutive `*` characters is also invalid. +- `[...]` matches any character inside the brackets. + Ranges of characters can also be specified, as ordered by Unicode, so e.g. + `[0-9]` specifies any character between 0 and 9 inclusive. +- `[!...]` is the negation of `[...]`, i.e. it matches any characters **not** in the brackets. + +Some examples: + +- `dist/**` matches the dist directory and all files in this directory. +- `**/test/**` matches all files under any directory named `test`, regardless of where they are. E.g. `dist/test`, `src/test`. +- `**/*.js` matches all files ending with the extension `.js` in all directories. + +Biome uses a glob library that treats all globs as having a `**/` prefix. +This means that `src/**/*.js` and `**/src/**/*.js` are treated as identical. +They match both `src/file.js` and `test/src/file.js`. + +:::caution +These patterns can be used in a Biome configuration file. +Glob patterns used on the command line are not interpreted by Biome. +They are expanded by your shell. +Some shells don't support the recursive glob `**` +::: diff --git a/src/content/docs/guides/getting-started.mdx b/src/content/docs/guides/getting-started.mdx index 5056c3589..0beb6471f 100644 --- a/src/content/docs/guides/getting-started.mdx +++ b/src/content/docs/guides/getting-started.mdx @@ -86,6 +86,7 @@ Alternatively, you can use a dedicated [CI Action](/recipes/continuous-integrati Success! You're now ready to use Biome. 🥳 - [Migrate from ESLint and Prettier](/guides/migrate-eslint-prettier) +- Learn more about how to [configure Biome](/guides/configure-biome) - Learn more about how to use and configure the [formatter](/formatter) - Learn more about how to use and configure the [linter](/linter) - Get familiar with the [CLI options](/reference/cli) diff --git a/src/content/docs/guides/how-biome-works.mdx b/src/content/docs/guides/how-biome-works.mdx deleted file mode 100644 index 58b952213..000000000 --- a/src/content/docs/guides/how-biome-works.mdx +++ /dev/null @@ -1,374 +0,0 @@ ---- -title: How Biome works -description: Learn how Biome works, like assumptions, configuration and more. ---- - -import {FileTree} from '@astrojs/starlight/components'; - -This is a guide that explains how the tool works, assumptions, and internal information useful when setting up the project and the configuration file. - -## Configuration - -The configuration file is considered **optional**, Biome has good defaults. Use the configuration -file to change those defaults. - -The Biome configuration file is named `biome.json` or `biome.jsonc` and should be placed in the root directory of your project. -The root directory is usually the directory containing your project's `package.json`. - -:::note -If both `biome.json` and `biome.jsonc` are present in the same folder, the priority will be given to `biome.json` -::: - -The following configuration file enables the formatter, sets the indent style and line width, and disables the linter: - -```json title="biome.json" -{ - "formatter": { - "enabled": true, - "indentStyle": "space", - "lineWidth": 120 - }, - "linter": { - "enabled": false - } -} -``` - -### Configuration file resolution - -Biome uses auto discovery to find the nearest configuration file. It starts looking for one in the current -working directory, and then it starts looking in the parent directories until: -- it finds a `biome.json` or a `biome.jsonc` file; -- it applies Biome's defaults if **no configuration file is found**. - -Here's an example: - - -- app - - backend - - package.json - - biome.json - - frontend - - legacy - - package.json - - new - - package.json - - biome.json - - - -- Biome commands that run in `app/backend/package.json` will use the configuration file `app/backend/biome.json`; -- Biome commands that run in `app/frontend/legacy/package.json` and `app/frontend/new/package.json` -will use the configuration file `app/frontend/biome.json`; - -:::note -Biome commands support using the `--config-path` option. This allows you to specify a custom configuration file or a directory where Biome can look for a `biome.json` or `biome.jsonc` file. When you use `--config-path`, the standard configuration file resolution process is **disabled**. - -If `--config-path` points directly to a file, you can use names other than `biome.json` or `biome.jsonc`. Biome will read a `.json` file using a standard JSON parser. For files with other extensions, Biome will treat them as `.jsonc` files, using a more flexible JSON parser that allows comments and trailing commas. -::: - -:::caution -Biome doesn't support nested `biome.json` files, neither in CLI nor in LSP. [Follow and help the support in the related issue](https://github.com/biomejs/biome/issues/2228) -::: - -### The `extends` option - -The `extends` option allows you to split your configuration across multiple files. This way, you can share common settings across different projects or folders. - -Here's an example of how you might set up your `biome.json` to extend other configuration files: - -```json title="biome.json" -{ - "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json", - "extends": ["./formatter.json", "./linter.json"] -} -``` - -For instance, you could define formatter settings in `formatter.json`: - -```json title="formatter.json" -{ - "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json", - "formatter": { - "indentWidth": 2 - }, - "javascript": { - "formatter": { - "semicolons": "asNeeded" - } - } -} -``` - -And linter rules in `linter.json`: - -```json title="linter.json" -{ - "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json", - "linter": { - "rules": { - "complexity": { - "noUselessConstructor": "off" - } - } - } -} -``` - -The entries defined in this array: -- must exist in the file system; -- are resolved from the path where the `biome.json` file is defined; -- must be relative paths or [paths to library](#extend-biomejson-from-a-library) -- must be reachable by Biome, e.g. symbolic links might not be resolved by Biome, if they are relative paths; -- are processed in the order they are listed, with settings in later files overriding earlier ones; - -### Extend `biome.json` from a library - -Starting from version `v1.6.0`, Biome is able to resolve configuration files from the `node_modules/` directory. So you can export your configuration file from a library, and import it in multiple projects. - -In order to do so, the first thing to do is to set up your "shared" Biome configuration in a certain way. Let's suppose that your library is called `@org/shared-configs`, and you want to import the Biome configuration using the specifier `@org/shared-configs/biome`. You have to set up the `package.json` in a specific way: - -```json title="package.json" ins={5,3} -{ - "name": "@org/shared-configs", - "type": "module", - "exports": { - "./biome": "./biome.json" - } -} -``` - -:::note -You can also export `biome.jsonc` files. Just change `./biome.json` to `./biome.jsonc`. -::: - -Make sure that `@org/shared-configs` is correctly installed in your project, and update the `biome.json` file to look like the following snippet: - -```json title="biome.json" -{ - "extends": ["@org/shared-configs/biome"] -} -``` - -Biome will attempt to **resolve** your library `@org/shared-configs/` from your working directory. The working directory is: -- when using the CLI, the directory where you execute your scripts from. Usually it matches the location of your `package.json` file; -- when using the LSP, the root directory of your project. - -:::caution -To avoid a breaking change with how the existing resolution works, paths starting with a dot `.` or ending with `.json` or `.jsonc` **won't** be resolved from `node_modules/`. -::: - -For more information about the resolution algorithm, refer to the [Node.js documentation](https://nodejs.org/api/esm.html#resolution-and-loading-algorithm). - -### Resolution of globs and paths - -Globs and relative file paths are resolved from the working directory. The working directory is: -- in a CLI context, the directory where you run the biome command; -- in a LSP context, is the root directory - -This means that if you take advantage of the [configuration file resolution](#configuration-file-resolution), you run a CLI command from a folder, and the configuration file is found in some **parent folder**, the paths/globs present on said files will be relative from where the command was run. Let's see an example: - - -- ~home/ - - biome.json - - www/ - - todo-app/ - - dist/ - - src/ - - package.json - - - -```json title="~home/biome.json" -{ - "files": { - "ignore": ["dist/**"] - } -} -``` - -```json title="~home/www/todo-app/package.json" -{ - "scripts": { - "check": "biome check ./" - } -} -``` - -Given the previous example, when you run the command `npm run check`, Biome will eventually find the configuration file in `~home`. Since the command was run from `~home/www/too-app`, that folder is considered the **working directory**. Biome will read the `files.ignore` option, and all those entries will be resolved from `~home/www/todo-app`.json - - -## Well-known Files - -Here are some well-known files that we specifically treat based on their file names, rather than their extensions. Currently, the well-known files are JSON-like files only, but we may broaden the list to include other types when we support new parsers. - -### JSON-like Files - -The following files are parsed as `JSON` files with both the options `json.parser.allowComments` and `json.parser.allowTrailingCommas` set to `false`. - -- `.all-contributorsrc` -- `.arcconfig` -- `.auto-changelog` -- `.bowerrc` -- `.c8rc` -- `.htmlhintrc` -- `.imgbotconfig` -- `.jslintrc` -- `.nycrc` -- `.tern-config` -- `.tern-project` -- `.vuerc` -- `.watchmanconfig` -- `mcmod.info` - -The following files are parsed as `JSON` files with the options `json.parser.allowComments` set to `true` but `json.parser.allowTrailingCommas` set to `false`. This is because the tools consuming these files can only strip comments. - -- `.ember-cli` -- `.eslintrc.json` -- `.jscsrc` -- `.jshintrc` -- `tslint.json` - -The following files are parsed as `JSON` files with the options `json.parser.allowComments` and `json.parser.allowTrailingCommas` set to `true`. This is because the tools consuming these files are designed to accommodate such settings. - -- `.babelrc` -- `.babelrc.json` -- `.devcontainer.json` -- `.hintrc` -- `.hintrc.json` -- `.swcrc` -- `api-documenter.json` -- `api-extractor.json` -- `babel.config.json` -- `deno.json` -- `devcontainer.json` -- `dprint.json` -- `jsconfig.json` -- `jsr.json` -- `language-configuration.json` -- `tsconfig.json` -- `typedoc.json` -- `typescript.json` - - -## Protected Files - -The following files are currently ignored by Biome. This means that no diagnostics will be ever emitted by Biome for those files. - -- `composer.lock` -- `npm-shrinkwrap.json` -- `package-lock.json` -- `yarn.lock` - - -## `include` and `ignore` explained - -Biome will resolve the globs specified in `include` and `ignore` relatively from the working directory. - -The working directory is the directory where you usually run a CLI command. -This means that you have to place **particular attention** when the configuration file is placed in -a different directory from where you execute your command. - -For example, let's take a project that contains two directories `backend/` and `frontend/` -and a Biome configuration file `biome.json` at the root directory of the project. -Inside the `frontend/` directory, a `package.json` specifies a `format` script that runs Biome: - - -- backend - - ... -- biome.json -- frontend - - package.json - - src - - ... - - test - - ... - - - -```json title="biome.json" -{ - "files": { - "include": ["src/**/*.js", "src/**/*.ts"] - }, - "formatter": { - "indentStyle": "space" - } -} -``` - -```json title="frontend/package.json" -{ - "name": "frontend-project", - "scripts": { - "format": "biome format --write ./" - } -} -``` - -When you run the script `format` from `frontend/package.json`, -the working directory resolved by that script will be `frontend/`. -The globs `src/**/*.js` and `src/**/*.ts` will have as "base" directory `frontend/`. - -At the moment, Biome uses a glob library that treats all globs as having a `**/` prefix. -This means that `src/**/*.js` and `**/src/**/*.js` are treated as identical. -They match both `src/file.js` and `test/src/file.js`. -This is something we plan to fix in Biome **v2.0.0**, as it will be a breaking change. -To avoid traversing the `test` folder, you can use the `ignore` field: - -```json title="biome.json" -{ - "files": { - "include": ["src/**/*.js", "src/**/*.ts"], - "ignore": ["test"] - }, - "formatter": { - "indentStyle": "space" - } -} -``` - -:::note -`include` and `ignore` have a slightly different semantics. -`ignore` applies to both regular files and folders, -while `include` is only tested on regular files. -This means that if you want to prevent Biome from traversing a folder, -you have to add the folder to `ignore`. -This is a current limitation that we will fix in a future release. -::: - -:::caution -`ignore` and `include` inside `overrides` have a **different** semantics: -- for `ignore`: if a file matches the globs, **_don't_ apply** the configuration inside this override, and keep apply the next overrides; -- for `include`: if a file matches the globs, **apply** the configuration inside this override, and keep apply the next overrides; -::: - - -### Glob syntax explained - -A glob pattern specifies a set of filenames. -Biome supports the following globs: - -- `*` matches zero or more characters. It cannot match the path separator `/`. -- `**` recursively matches directories and files. - This sequence **must** form a single path component, - so both `**a` and `b**` are invalid and will result in an error. - A sequence of more than two consecutive `*` characters is also invalid. -- `[...]` matches any character inside the brackets. - Ranges of characters can also be specified, as ordered by Unicode, so e.g. - `[0-9]` specifies any character between 0 and 9 inclusive. -- `[!...]` is the negation of `[...]`, i.e. it matches any characters **not** in the brackets. - -Some examples: - -- `dist/**` matches the dist directory and all files in this directory. -- `**/test/**` matches all files under any directory named `test`, regardless of where they are. E.g. `dist/test`, `src/test`. -- `**/*.js` matches all files ending with the extension `.js` in all directories. - -These patterns can be used in a Biome configuration file. - -:::caution -Glob patterns used on the command line are not interpreted by Biome. -They are expanded by your shell. -Some shells don't support the recursive glob `**` -::: diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 325fd25c7..318cf07f9 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -52,7 +52,7 @@ import NumberOfRules from "@/components/generated/NumberOfRules.astro";

Format code like Prettier, save time

- **Biome is a [fast formatter](https://github.com/biomejs/biome/tree/main/benchmark#formatting)** for _JavaScript_, _TypeScript_, _JSX_, and _JSON_ that scores **[97% compatibility with _Prettier_](https://console.algora.io/challenges/prettier)**, **saving CI and developer time**. + **Biome is a [fast formatter](https://github.com/biomejs/biome/tree/main/benchmark#formatting)** for _JavaScript_, _TypeScript_, _JSX_, _TSX_ and _JSON_ that scores **[97% compatibility with _Prettier_](https://console.algora.io/challenges/prettier)**, **saving CI and developer time**. Biome can even **format malformed code** as you write it in [your favorite editor](/guides/integrate-in-editor/). diff --git a/src/content/docs/internals/language-support.mdx b/src/content/docs/internals/language-support.mdx index cb584636c..2b788e094 100644 --- a/src/content/docs/internals/language-support.mdx +++ b/src/content/docs/internals/language-support.mdx @@ -49,7 +49,7 @@ For files with an extension name of `.jsonc` or those identified as `jsonc` acco Please note, some well-known files like `tsconfig.json` and `.babelrc` don't use the `.jsonc` extension but still allow comments and trailing commas. While others, such as `.eslintrc.json`, only allow comments. Biome is able to identify these files and adjusts the `json.parser.allowTrailingCommas` option accordingly to ensure they are correctly parsed. -[This section](../../guides/how-biome-works#well-known-files) gives the full list of well-known files that Biome can recognize. +[This section](../../guides/configure-biome#well-known-files) gives the full list of well-known files that Biome can recognize. ## HTML super languages support diff --git a/src/content/docs/ja/guides/how-biome-works.mdx b/src/content/docs/ja/guides/configure-biome.mdx similarity index 100% rename from src/content/docs/ja/guides/how-biome-works.mdx rename to src/content/docs/ja/guides/configure-biome.mdx diff --git a/src/content/docs/ja/internals/language-support.mdx b/src/content/docs/ja/internals/language-support.mdx index 38bbfce25..9035d22b5 100644 --- a/src/content/docs/ja/internals/language-support.mdx +++ b/src/content/docs/ja/internals/language-support.mdx @@ -47,7 +47,7 @@ JSONCは「コメント付きJSON」の略です。この形式は、[VS Code](h `tsconfig.json` や `.babelrc` などのよく知られたファイルは `.jsonc` 拡張子を使用しませんが、コメントや末尾のカンマを許可するものもあります。一方、 `.eslintrc.json` のようなファイルはコメントのみを許可します。Biomeはこれらのファイルを識別し、適切に `json.parser.allowTrailingCommas` オプションを調整して正しくパースできるようにします。 -[このセクション](/ja/guides/how-biome-works#既知のファイル)では、Biomeが認識できる既知のファイルの完全なリストを提供しています。 +[このセクション](/ja/guides/configure-biome#既知のファイル)では、Biomeが認識できる既知のファイルの完全なリストを提供しています。 ## HTML拡張言語のサポート diff --git a/src/content/docs/linter/index.mdx b/src/content/docs/linter/index.mdx index c9c52c529..a0b9301f2 100644 --- a/src/content/docs/linter/index.mdx +++ b/src/content/docs/linter/index.mdx @@ -206,7 +206,7 @@ You can set them by shaping the value of the rule differently. ``` -## Ignoring code +## Ignore code There are times when a developer wants to ignore a lint rule for a specific line of the code. You can achieve this by adding a suppression comment above the line that emits the lint diagnostic. @@ -234,35 +234,12 @@ debugger; debugger; ``` - -## Ignoring files - Biome doesn't provide ignore comments that ignore an entire file. -However, you can ignore a file using the Biome configuration file. - -You can ignore files for all tools, including the linter, -using the [`files.ignore` configuration](/guides/how-biome-works#include-and-ignore-explained). -By default, Biome ignores the [protected files](/guides/how-biome-works#protected-files). - -If you want to exclude files from being linted, you can use `linter.ignore`: - -```jsonc title="biome.jsonc" -{ - "files": { - // All tools, including the linter, ignore following files - "ignore": ["dist/**"] - }, - "linter": { - // Only the linter ignores the following files - "ignore": ["test/**"] - } -} -``` - +However, you can [ignore a file using the Biome configuration file](/guides/configure-biome/#ignore-files). Note that you can also [ignore the files ignored by your VCS](/guides/integrate-in-vcs#use-the-ignore-file). -## Migrating from other linters +## Migrate from other linters Many of Biome lint rules are inspired from other linters. If you want to migrate from other linters such as ESLint or `typescript-eslint`, diff --git a/src/content/docs/pt-br/guides/how-biome-works.mdx b/src/content/docs/pt-br/guides/configure-biome.mdx similarity index 100% rename from src/content/docs/pt-br/guides/how-biome-works.mdx rename to src/content/docs/pt-br/guides/configure-biome.mdx diff --git a/src/content/docs/zh-cn/guides/how-biome-works.mdx b/src/content/docs/zh-cn/guides/configure-biome.mdx similarity index 100% rename from src/content/docs/zh-cn/guides/how-biome-works.mdx rename to src/content/docs/zh-cn/guides/configure-biome.mdx