How Biome works

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

Section titled 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 and should be placed in the root directory of your project. The root directory is usually the directory containing your project’s package.json.

Since version 1.6.0, Biome accepts also the file biome.jsonc.

Note

If both biome.json and biome.jsonc are present in the same folder, the priority will be given to biome.json

This configuration file enables the formatter and sets the preferred indent style and width. The linter is disabled:

biome.json

{
  "formatter": {
    "enabled": true,
    "indentStyle": "tab",
    "lineWidth": 120
  },
  "linter": {
    "enabled": false
  }
}

Default configuration

Section titled Default configuration

When you run biome init, the default configuration emitted is the following:

biome.json

{
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true }
  }
}

Configuration file resolution

Section titled 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:

• Directoryapp

  • Directorybackend

    • package.json
    • biome.json
  • Directoryfrontend

    • Directorylegacy

      • package.json
    • Directorynew

      • 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

Most Biome commands support using the --config-path command line 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 relative issue

The extends option

Section titled 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:

biome.json

{
  "$schema": "https://biomejs.dev/schemas/1.7.3/schema.json",
  "extends": ["./formatter.json", "./linter.json"]
}

For instance, you could define formatter settings in formatter.json:

formatter.json

{
  "$schema": "https://biomejs.dev/schemas/1.7.3/schema.json",
  "formatter": {
    "indentSize": 2
  },
  "javascript": {
    "formatter": {
      "semicolons": "asNeeded"
    }
  }
}

And linter rules in linter.json:

linter.json

{
  "$schema": "https://biomejs.dev/schemas/1.7.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
• 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

Section titled 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:

package.json

{
  "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 and it should work.

Make sure that @org/shared-configs is correctly installed in your project, and update the biome.json file to look like the following snippet:

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.

Resolution of globs and paths

Section titled 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, 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:

• Directory~home/

  • biome.json
  • Directorywww/

    • Directorytodo-app/

      • Directorydist/

        • …
      • Directorysrc/

        • …
      • package.json

~home/biome.json

{
  "files": {
    "ignore": ["dist/**"]
  }
}

~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

Protected Files

Section titled 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

Well-known Files

Section titled 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

Section titled 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

include and ignore explained

Section titled 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, you have a project that contains two directories called backend/ and frontend/, and decide to place your biome.json at the root folder of the project. Inside the frontend/ project, you have your package.json with some scripts that run Biome:

• Directorybackend

  • …
• biome.json
• Directoryfrontend

  • package.json
  • Directorysrc

    • …
  • Directorytest

    • …

biome.json

{
  "files": {
    "include": ["src/**/*.js", "src/**/*.ts"]
  },
  "formatter": {
    "indentStyle": "space"
  }
}

frontend/package.json

{
  "name": "frontend-project",
  "scripts": {
    "format": "biome format --write ./"
  }
}

When you run the script format inside 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/.

Although include doesn’t contain test, Biome will still traverse the folder.

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

Section titled Glob syntax explained

The syntax and meaning of these two options loosely follow the globset rules but without the ability to set options.

• * matches zero or more characters.- ** recursively matches directories but are only legal in three situations. First, if the glob starts with **/, then it matches all directories. For example, **/foo matches foo and bar/foo but not foo/bar. Secondly, if the glob ends with /**, then it matches all sub-entries. For example, foo/** matches foo/a and foo/a/b, but not foo. Thirdly, if the glob contains /**/ anywhere within the pattern, then it matches zero or more directories. Using ** anywhere else is illegal (N.B. the glob ** is allowed and means “match everything”).- Metacharacters such as * and ? can be escaped with character class notation. e.g., [*] matches *.

Check the wikipedia page for more information.