---
title: "VS Code and Positron"
editor:
  markdown:
    wrap: sentence
    canonical: true
---

Air provides first class support for both VS Code and Positron, which both support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).

# Installation

Air is available as a [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Posit.air-vscode) for VS Code.

Air comes pre-bundled with Positron.
It is available as an [OpenVSX Extension](https://open-vsx.org/extension/posit/air-vscode) that is already installed for you.

The extension for both VS Code and Positron comes with an Air binary, so you don't need anything else to get going!

## User vs Workspace settings

VS Code and Positron give you the ability to edit settings at a *user* level and at a *workspace* level (i.e. for just the current project you are working on).
To enable some Air features, like [Format on Save](#editor-vs-code-format-on-save), you'll need to adjust settings in either your user or workspace level `settings.json` file.
We generally recommend modifying workspace level settings for two reasons:

-   Workspace level settings exist inside your workspace folder at `.vscode/settings.json` and are checked in to your version control system.
    This means that your collaborators will get those settings automatically when they check out your project.
    User level settings are not checked in to version control.

-   User level settings are automatically applied for *all* projects that you open.
    While this sounds nice, if you open an older project (or a project you don't own) that doesn't use Air, then you'll have to remember to turn off your user level Air settings before committing to that project, otherwise you may create a large amount of format related diffs that the project may not want.

The easiest way to set up a workspace level `settings.json` with the recommended settings is by running the command `Air: Initialize Workspace Folder`.
This is equivalent to running [`usethis::use_air()`](https://usethis.r-lib.org/dev/reference/use_air.html) from an R console.

Alternatively, to open your `settings.json` file from the Command Palette (`Cmd + Shift + P` on Mac/Linux, `Ctrl + Shift + P` on Windows):

-   Run `Preferences: Open Workspace Settings (JSON)` to modify workspace specific settings (recommended).
-   Run `Preferences: Open User Settings (JSON)` to modify global user settings.

# Features

## Format on save {#editor-vs-code-format-on-save}

Once you have the extension installed, turn on Format on Save for R documents by opening your `settings.json` and adding:

``` json
{
    "[r]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "Posit.air-vscode"
    }
}
```

Note that running the command `Air: Initialize Workspace Folder` will add this to your `settings.json` for you.

You should now be able to simply open an R document, save it, and have the entire document formatted by Air.
You can also explicitly call the command `Format Document` if you'd like to control the timing of formatting manually.

<!--# Come back and add video -->

## Format selection

To format a selection of code, highlight it with your cursor and run the command `Format Selection`.
Formatting a selection may *expand* that selection to find the nearest complete fragment of code that is formattable.

<!--# Come back and add video -->

## Format workspace folder

Air ships with a special `Air: Format Workspace Folder` command to format all R files within a workspace folder.
This is particularly useful when transitioning an existing project over to Air, where you need to perform a project-wide format before utilizing the per-file format on save feature.

Note that if you don't have an `air.toml` in your project, then this command will use Air's default settings rather than the IDE [settings synchronization mechanism](configuration.qmd#configuration-settings-synchronization).
We recommend using the command `Air: Initialize Workspace Folder` to set up an `air.toml` (among other things) before running this command.

## Quarto

Quarto can automatically invoke Air on R code cells when the [Quarto extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) is active.

### Format on save

To format all R code cells on save, set this in your `settings.json`:

``` json
{
    "[r]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "Posit.air-vscode"
    },
    "[quarto]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "quarto.quarto"
    }
}
```

Note that running the command `Air: Initialize Workspace Folder` will add this to your `settings.json` for you.

<!--# Come back and add video -->

### Format cell

When inside an R cell in a Quarto document, use the chorded key combination `Cmd+K Cmd+F` or the command `Quarto: Format Cell` to format a single cell.

<!--# Come back and add video -->

## Configuration autocompletion and validation

Installing the [Tombi](https://github.com/tombi-toml/tombi) extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=tombi-toml.tombi) or the [OpenVSX Marketplace](https://open-vsx.org/namespace/tombi-toml) activates autocompletion and validation while inside an `air.toml` file.
We highly recommend using this extension for an enjoyable `air.toml` editing experience!

![](images/vscode/autocomplete-overview.png){fig-align="center"}

![](images/vscode/autocomplete-line-ending.png){fig-align="center"}
