Skip to content

Commit

Permalink
docs: improve guides, add 'Migrate from' page
Browse files Browse the repository at this point in the history
  • Loading branch information
Conaclos committed Apr 23, 2024
1 parent b9141cf commit 6ef1bca
Show file tree
Hide file tree
Showing 12 changed files with 278 additions and 117 deletions.
4 changes: 4 additions & 0 deletions astro.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,10 @@ export default defineConfig({
"pt-BR": "Integrando o Biome com o seu VCS",
},
},
{
label: "Migrate from ESLint and Prettier",
link: "/guides/migrate-eslint-prettier",
},
],
},
{
Expand Down
42 changes: 17 additions & 25 deletions src/content/docs/guides/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,12 @@ description: Learn how to set up a new project with Biome.
import PackageManagerBiomeCommand from "@/components/PackageManagerBiomeCommand.astro";
import PackageManagerCommand from "@/components/PackageManagerCommand.astro";

## System Requirements

- Windows (including WSL), macOS, or Linux
- x86_64 or ARM64
- Node.js v14.18 or newer (not applicable if you use the standalone executable)

## Installation

The fastest way to download Biome is to use `npm` or your preferred package manager. The CLI is also available as a [standalone executable](/guides/manual-installation) if you want to use Biome without installing Node.js.
The fastest way to download Biome is to use `npm` or your preferred package manager.
This requires Node.js v14.18 or newer.

The CLI is also available as a [standalone executable](/guides/manual-installation) if you want to use Biome without installing Node.js.

To install Biome, run the following commands in a directory containing a `package.json` file.

Expand All @@ -25,19 +22,15 @@ To install Biome, run the following commands in a directory containing a `packag
bun="add --dev --exact @biomejs/biome"
/>

:::note
It is also possible to install Biome globally rather than locally.
However, this is not recommended.
:::

It's **highly recommended** not to use range operators when installing Biome.
Check the [versioning page](/internals/versioning/) for more information.
It's **highly recommended** not to use a range operator when installing Biome.
See the [versioning page](/internals/versioning/) for more information.

## Configuration

We recommend creating a `biome.json` configuration file for each project.
It eliminates the need to repeat the CLI options every time you run a command and ensures that Biome applies the same configuration in your editor. If you're happy with Biome's defaults, you don't have to create the configuration.

We recommend that you create a `biome.json` configuration file for each project.
This eliminates the need to repeat the CLI options each time you run a command,
and ensures that Biome uses the same configuration in your editor.
If you are happy with Biome's defaults, you don't need to create the configuration.
To create the configuration, run the `init` command in the root folder of your project:

<PackageManagerBiomeCommand command="init"/>
Expand Down Expand Up @@ -84,26 +77,25 @@ You can apply **both** of them by leveraging the [`check`](/reference/cli#biome-

<PackageManagerBiomeCommand command="check --apply <files>"/>

The command `check` is command meant to run multiple tools at once. Currently, it does:

- format files
- lint files
- organize imports
The `check` command runs multiple tools at once.
It fomats, lints, and organizes imports.

## Install an editor plugin

We recommend installing an editor plugin to get the most out of Biome. Check out the [editor page](/guides/integrate-in-editor) to know which editors support Biome.
We recommend installing an editor plugin to get the most out of Biome.
Check out the [editor page](/guides/integrate-in-editor) to know which editors support Biome.

## CI Setup

If you're using Node.js, the recommended way to run Biome in CI is to use [your favourite package manager](/guides/getting-started#installation).
If you're using Node.js, the recommended way to run Biome in CI is to use [your preferred package manager](/guides/getting-started#installation).
This ensures that your CI pipeline uses the same version of Biome as you do inside the editor or when running local CLI commands.
Alternatively, you can use dedicated [CI Actions](/recipes/continuous-integration/).
Alternatively, you can use a dedicated [CI Action](/recipes/continuous-integration).

## Next Steps

Success! You're now ready to use Biome. 🥳

- [Migrate from ESLint and Prettier](/guides/migrate-eslint-prettier)
- 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)
Expand Down
10 changes: 5 additions & 5 deletions src/content/docs/guides/integrate-in-editor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,17 @@ These are plugins that are maintained by the Biome team and part of the [Biome o

The Biome editor integration allows you to:

* Format files on save or when issuing the Format command.
* Format files on save or when issuing the _Format_ command.
* Lint files and apply code fixes

Install our official [Biome VS Code extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) from the Visual Studio Marketplace.

To make Biome the default formatter open a [supported file](/internals/language-support/) and:

* open the *Command Palette* (View or <kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>)
* select *Format Document With...*
* select *Configure Default Formatter*
* select *Biome*.
1. open the *Command Palette* (View or <kbd>Ctrl</kbd>/<kbd title="Cmd">⌘</kbd>+<kbd title="Shift">⇧</kbd>+<kbd>P</kbd>)
1. select *Format Document With...*
1. select *Configure Default Formatter*
1. select *Biome*.

### IntelliJ

Expand Down
19 changes: 16 additions & 3 deletions src/content/docs/guides/integrate-in-vcs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,9 @@ This configuration doesn't do **anything per se**. You have to opt-in new featur

### Use the ignore file

This is a feature that allows Biome to read the ignore file of the VCS and ignore all the files and folders that were specified in it. This is an opt-in feature, and you have to enable the `vcs.useIgnoreFile` field:
This is a feature that allows Biome to read the ignore file of the VCS and ignore all the files and folders that were specified in it.
For now, Biome only **takes the ignore file in the working directory into account**.
This is an opt-in feature, and you have to enable the `vcs.useIgnoreFile` field:

```json title="biome.json" ins={5}
{
Expand Down Expand Up @@ -53,7 +55,7 @@ First, you have to update your configuration file and tell Biome what's the defa
Then, add the `--changed` option to your command, to process only those files that your VCS acknowledged as "changed". Biome, with the help of the VCS, will determine the changed file from the branch `main` and your current revision:

```shell
biome format --changed
biome check --changed
```

:::caution
Expand All @@ -63,5 +65,16 @@ Biome doesn't check what's changed, this means that even adding spaces or newlin
Alternatively, you can use the option `--since` to specify an arbitrary branch. This option **takes precedence** over the option `vcs.defaultBranch`. For example, you might want to check your changes against the `next` branch:

```shell
biome format --changed --since=next
biome check --changed --since=next
```

### Process only staged files

Before committing your changes, you may want to check the formatting and lints files that have been added to the _index_, also known as _staged files_.
Add the `--staged` option to your command, to process only those files:

```shell
biome check --staged
```

The `--staged' option is not available on the `ci' command because you are not expected to commit changes in a CI environment.
29 changes: 11 additions & 18 deletions src/content/docs/guides/manual-installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,14 @@ title: Manual installation
description: Install the Biome manually
---

## Use Biome without Node.js

Using Biome's standalone CLI binary can be a great choice if you aren't already using Node or npm (or any other package manager).
Using Biome's standalone CLI binary can be a great choice if you aren't already using Node.js or `npm` (or any other package manager).
Or in other words, Biome shouldn't be the only reason for you to have a `package.json`.

:::note
If you're already using npm or another package manager, then using the package manager is the [preferred way to install](/guides/getting-started#installation) Biome.
If you're already using `npm` or another package manager, then using the package manager is the [preferred way to install](/guides/getting-started#installation) Biome.
You're already familiar with the tooling, and installing and updating are simpler.
:::

### Homebrew

Biome is available as a [Homebrew formula](https://formulae.brew.sh/formula/biome) for macOS and Linux users.

```shell
brew install biome
```

## System Requirements

- Windows (including WSL), macOS, or Linux
- x86_64 or ARM64

## Supported platforms

You have to pick the correct binary for your platform for Biome work. The following table should help you do so.
Expand All @@ -39,7 +24,15 @@ You have to pick the correct binary for your platform for Biome work. The follow
Use the Linux variant for Windows Subsystem for Linux (WSL).
:::

## Install Biome
## Homebrew

Biome is available as a [Homebrew formula](https://formulae.brew.sh/formula/biome) for macOS and Linux users.

```shell
brew install biome
```

## Using a published binary

To install Biome, grab the executable for your platform from the [latest CLI release](https://github.com/biomejs/biome/releases) on GitHub and give it execution permission.

Expand Down
189 changes: 189 additions & 0 deletions src/content/docs/guides/migrate-eslint-prettier.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
---
title: Migrate from ESLint and Prettier
description: Learn how you can ease your migration from ESLint and Prettier
---

import PackageManagerBiomeCommand from "@/components/PackageManagerBiomeCommand.astro";

Biome provides dedicated commands to ease the migration from ESLint and Prettier.

## Migrate from ESLint

Many Biome linter rules are inspired by or identical to the ESLint rules or the rules of an ESLint plugin.
We handle some ESLint plugins such as [TypeScript ESLint](https://typescript-eslint.io/), [ESLint JSX A11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y), [ESLint React](https://github.com/jsx-eslint/eslint-plugin-react), and [ESLint Unicorn](https://github.com/sindresorhus/eslint-plugin-unicorn).
However, Biome has its own naming convention for its rules.
Biome uses `camelCaseRuleName` while ESLint uses `kebab-case-rule-name`.
Moreover, Biome has often chosen to use different names to better convey the intent of its rules.
The source of a rule can be found on the page describing the rule.
You can also find the equivalent Biome rule from an ESLint rule using the [dedicated page](/linter/rules-sources).

To ease the migration, Biome provides the `biome migrate eslint` subcommand.
This subcommand will read your ESLint configuration and attempt to port its settings to Biome.
The subcommand is able to handle both the legacy and the flat configuration files.
It supports the `extends` field of the legacy configuration and loads both shared and plugin configurations.
The subcommand also migrates `.eslintignore`.

Given the following ESLint configuration:

```json title=".eslintrc.json"
{
"extends": ["plugin:unicorn/recommended"],
"plugins": ["unicorn"],
"ignore_patterns": ["dist/**"],
"globals": {
"Global1": "readonly"
},
"rules": {
"eqeqeq": "error"
},
"overrides": [
{
"files": ["tests/**"],
"rules": {
"eqeqeq": "off"
}
}
]
}
```

And the following Biome configuration:

```json title="biome.json"
{
"linter": {
"enabled": true,
"rules": {
"recommended": true
}
}
}
```

Run the following command to migrate your ESLint configuration to Biome.

<PackageManagerBiomeCommand command="migrate eslint --write"/>

The subcommand overwrites your initial Biome configuration.
For example, it disables `recommended`.
This results in the following Biome configuration:

```json title="biome.json"
{
"organizeImports": { "enabled": true },
"linter": {
"enabled": true,
"rules": {
"recommended": false,
"complexity": {
"noForEach": "error",
"noStaticOnlyClass": "error",
"noUselessSwitchCase": "error",
"useFlatMap": "error"
},
"style": {
"noNegationElse": "off",
"useForOf": "error",
"useNodejsImportProtocol": "error",
"useNumberNamespace": "error"
},
"suspicious": {
"noDoubleEquals": "error",
"noThenProperty": "error",
"useIsArray": "error"
}
}
},
"javascript": { "globals": ["Global1"] },
"overrides": [
{
"include": ["tests/**"],
"linter": { "rules": { "suspicious": { "noDoubleEquals": "off" } } }
}
]
}
```

The subcommand needs Node.js to load and resolve all the plugins and `extends` configured in the ESLint configuration file.
For now, `biome migrate eslint` doesn't support configuration written in YAML.

By default, Biome doesn't migrate inspired rules.
You can use the CLI flag `--include-inspired` to migrate them.

<PackageManagerBiomeCommand command="migrate eslint --write --include-inspired"/>

Note that you are unlikely to get exactly the same behavior as ESLint because Biome has chosen not to implement some rule options or to deviate slightly from the original implementation.

Since ESLint takes VCS ignore files into account,
we recommend that you enable Biome's [VCS integration](/guides/integrate-in-vcs).

## Migrate from Prettier

Biome tries to match the Prettier formatter as closely as possible.
However, Biome uses different defaults for its formatter.
For example, it uses tabs for indentation instead of spaces.
You can easily migrate to Biome by running `biome migrate prettier --write`.

Given the following Prettier configuration:

```json title=".prettierrc.json"
{
"useTabs": false,
"singleQuote": true,
"overrides": [
{
"files": ["*.json"],
"options": { "tabWidth": 2 }
}
]
}
```

Run the following command to migrate your Prettier configuration to Biome.

<PackageManagerBiomeCommand command="migrate prettier --write"/>

This results in the following Biome configuration:

```json title="biome.json"
{
"formatter": {
"enabled": true,
"formatWithErrors": false,
"indentStyle": "space",
"indentWidth": 2,
"lineEnding": "lf",
"lineWidth": 80,
"attributePosition": "auto"
},
"organizeImports": { "enabled": true },
"linter": { "enabled": true, "rules": { "recommended": true } },
"javascript": {
"formatter": {
"jsxQuoteStyle": "double",
"quoteProperties": "asNeeded",
"trailingComma": "all",
"semicolons": "asNeeded",
"arrowParentheses": "always",
"bracketSpacing": true,
"bracketSameLine": false,
"quoteStyle": "single",
"attributePosition": "auto"
}
},
"overrides": [
{
"include": ["*.json"],
"formatter": {
"indentWidth": 2
}
}
]
}
```

The subcommand needs Node.js to load JavaScript configurations such as `.prettierrc.js`.
`biome migrate prettier` doesn't support configuration written in JSON5, TOML, or YAML.

Since Prettier takes VCS ignore files into account,
we recommend that you enable Biome's [VCS integration](/guides/integrate-in-vcs).
Loading

0 comments on commit 6ef1bca

Please sign in to comment.