VS Code and Positron

Air provides first class support for both VS Code and Positron, which both support the Language Server Protocol.

Installation

Air is available as an Extension for both VS Code and Positron. The extension comes pre-bundled with an Air binary, so you don’t need anything else to get going! The Air extension is hosted in the VS Code Marketplace and on OpenVSX.

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, 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 usethis::use_air() (note that this currently requires the development version of usethis).

Alternatively, to open your settings.json file from the Command Palette (Cmd + P on Mac/Linux, Ctrl + 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

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

{
    "[r]": {
        "editor.formatOnSave": true
    }
}

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 this manually.

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.

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. We recommend using usethis::use_air() 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 is active.

Format on save

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

{
    "[quarto]": {
        "editor.formatOnSave": true
    },
    "[r]": {
        "editor.formatOnSave": true
    }
}

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.

Configuration autocompletion and validation

Installing the Even Better TOML extension activates autocompletion and validation while inside an air.toml file. There is a known issue regarding autocompletion duplication, but we still find this extension very useful!