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 ConfigurationThe 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
.
This configuration file enables the formatter and sets the preferred indent style and width. The linter is disabled:
Default configuration
Section titled Default configurationWhen you run biome init
, the default configuration emitted is the following:
Configuration file resolution
Section titled Configuration file resolutionBiome 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 abiome.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 fileapp/backend/biome.json
; - Biome commands that run in
app/frontend/legacy/package.json
andapp/frontend/new/package.json
will use the configuration fileapp/frontend/biome.json
;
The extends
option
Section titled The extends optionThe 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:
For instance, you could define formatter settings in formatter.json
:
And linter rules in linter.json
:
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 libraryStarting 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:
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 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.
For more information about the resolution algorithm, refer to the Node.js documentation.
Resolution of globs and paths
Section titled Resolution of globs and pathsGlobs 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
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 FilesThe 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 FilesHere 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 FilesThe 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 explainedBiome 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
- …
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.
Glob syntax explained
Section titled Glob syntax explainedA 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
andb**
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 namedtest
, 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.