Positron – @mjfrigaard

I’ve been trying out Posit’s new Positron IDE for a few weeks, so I put together a post covering my initial impressions of developing Shiny apps and R packages.

Why switch?

I use RStudio daily for R development and have no complaints about the IDE’s capabilities. However, I’ve recently started using VS Code for Python and JavaScript. When I heard about Positron, I wondered if it would offer enough overlapping features to allow me to use a single IDE for all three languages.

Positron was covered at posit::conf(2024), and the Getting Started article on the new website lists reasons you might (or might not) want to switch IDEs. I’ve summarized them below:

Switch

You use VS Code or JupyterLab for data science but want more features.
You want more customization in RStudio.
You program in languages other than R/Python.

Don’t switch

You need reliable and fully functioning software (Positron is still a work-in-progress, so some features may not be stable or polished).
You need all RStudio’s features (i.e., inline output for Quarto and R Markdown, Sweave, Add-In support, profiling, etc.). Not all these features are implemented in Positron.

Download and Install Positron

Positron now has a website with much of the information below (without the screenshots).

Positron can be downloaded from it’s GitHub repository. I’m running it on my MacBook (2019, 2.6 GHz 6-Core Intel Core i7, macOS Sonoma Version 14.5), so this involved downloading the .dmg file from the releases page and installing it like I would any new application.¹

IDE Layout

NOTE

Throughout this post, I’ll make the assumption the reader hasn’t spent much time in VS Code (if you have, Positron will be easier to navigate and use).

At first glance, Positron looks like VS Code, but with the four panes we’re used to seeing in RStudio. The default layout includes a Welcome pane with options for opening files and folders above the Panel, which displays the current version of R running:

The Panel is similar to the Console in RStudio but also includes tabs for Terminal, Problems, Output, etc.

The Session and Variables² panes are open and initially empty, but we can see this where our Plots will be displayed.

Session and Variables (click to enlarge)

Layout options

To customize Positron’s panes, we can use the layout presets icon (in the upper-right corner of the IDE).

Or we can position each pane manually via View > Appearance > Panel Position …

Positron’s view options (click to enlarge)

We’ll continue using the default ‘Stacked Layout’ configuration in this post, but I recommend exploring the other options to find a customization that fits your needs.

R & Python versions

I had R (R 4.4.1) and Python (3.11.5) previously installed, and Positron quickly located both R and Python versions (and displays them in multiple places in the IDE):

For more information on detecting Python and R versions, see the Interpreter Selection section of the documentation.

R Dependencies

Positron’s documentation recommends installing the following packages:³

pak::pak(c("usethis", "cli", "crayon", 
           "rlang", "roxygen2", "pkgload"))

Files, Folders and Projects

I use the folder icon in the upper right corner of the IDE to locate and open project folders. Still, Positron has multiple options for opening project folders from the welcome page and with the explorer sidebar menu item:

I’ll be using my sap repository because it contains the following:

Version control
An R project (i.e., with an .Rproj file)
A Shiny app
An R package⁴

Activity bar

One of Positron’s major distinguishing factors is its activity bar. This sidebar lets us open and edit files, perform searches, access source control (like Git), and find/install extensions.

I’ll briefly cover a few of Positron’s sidebar menu items in the sections below.

Explorer

As noted above, the Explorer menu item can open project files and folders.

This closely resembles the Files pane in RStudio.

Clicking on files in the Explorer will open them in the Editor. After opening files, the cursor location will also display additional information on hover (i.e., version control information):

Hover information in Editor (click to enlarge)

Search

The Search menu item allows us to find and replace across all files.

Similar to the Find in Files (Ctrl + Shift + F) window in RStudio.

RStudio ‘Find in Files’ (click to enlarge)

Source Control

The Source Control menu can open local Git folders and clone repositories.

When in a Git repo, it displays Git commits, branches, remotes, stashes, tags, work trees, and contributors (similar to the Git pane in RStudio).

In RStudio, I still use the Terminal for ~90% of my interactions with Git, but Positron also comes with a Source Control menu.⁵

Checking out Git branch with Source Control (click to enlarge)

Extensions

We can install Positron extensions from the Extensions menu item.

Positron’s extensions are somewhat similar to RStudio Addins but with a few key differences:

Positron extensions enhance the IDE’s capabilities by interacting with the VS Code API. They can range from language support (e.g., R, Python) to tools and features for general coding tasks (debugging, version control, syntax highlighting, code snippets, etc.)
RStudio Addins are custom tools and features to extend IDE’s functionality, focusing on R-specific tasks (package development, customizing visualizations, R markdown document generation, etc.)

Positron Extensions via Positron +1e (click to enlarge)

At a minimum, be sure to install the Posit Publisher extension. I’ve also installed Positron +1e, a collection of extensions curated by Garrick Aden-Buie⁶ for ‘git-backed data science and dev work shared primarily on GitHub’.

Positron Extensions

Extensions can be installed from VS Code Marketplace or the Open VXS Registry. VS Code Marketplace is maintained by Microsoft, ensuring high-quality and secure extensions, whereas the Open VXS Registry is an open-source alternative for those looking to avoid vendor lock-in.⁷ Most extensions on Open VXS Registry are identical to those found on the VS Code marketplace, but with a focus on open-source principles.

For more Positron extensions, I recommend checking out this post from Andrew Heiss⁸ and this LinkedIn post from Veerle van Leemput.⁹

Shiny Apps

I’ve checked out a branch of sap that’s in the early stages of development, so it’s a Shiny app (and not an R package yet).¹⁰ The image below highlights some of the IDE’s features after opening the app.R file:

Open app.R file (click to enlarge) — Open `app.R` file (click to enlarge)

Positron displays the current folder (or project) in a familiar location, and the active Git branch and Quarto version are conveniently placed in the footer.

As we can see from the image above, Positron displays much of the same information as the RStudio IDE but with a VS Codeish layout. The most notable change I had to adapt to was the new location of the project files in the file Explorer.

Running Applications

Positron detects that I’m developing a Shiny application and places a Run Shiny App icon at the top of the app.R file. Clicking the Run Shiny App button launches our application in the Viewer pane.

Terminal runs the Shiny app (click to enlarge)

Unlike RStudio, Positron runs Shiny applications from the Terminal with a dedicated Shiny process when the Run Shiny App button is clicked.

In the Terminal, a message tells us that autoreload has been turned on (which means we can make live updates to our application):

We’re also told that the application runs with the ‘minified’ JavaScript file (shiny.min.js), which results in using --devmode. Both of these options are covered in the Shiny documentation.

Run Shiny App Terminal Commands

I’ve broken down the Shiny terminal commands below:

The first commands specifies the Rscript interpreter, the scripting front-end for R. Rscript allows the execution of R scripts directly from the command line.

# Rscript interpreter 
$/usr/local/bin/Rscript

The next command is the path to an R script that comes with your Positron installation for running Shiny applications.

# runShinyApp.R Positron Shiny extension  
$/Users/username/.positron/extensions/posit.shiny-1.0.0-universal/rscripts/runShinyApp.R

You can view the contents of runShinyApp.R by passing the path into another Terminal window preceded by cat.

The final Terminal command is the path to the moviesApp Shiny application’s main app.R script (with two additional arguments):

# moviesApp app.R file
/Users/username/projects/apps/R/moviesApp/app.R 51146 --devmode

51146 specifies the port on which the Shiny application will run.
--devmode enables development mode for the Shiny application.¹¹

Stopping Applications

We can stop the application like we would any other Terminal process:

Ctrl + C

After stopping the application, you can clear the Viewer by clicking on the Clear the current URL icon in the upper-right corner.

These changes make application development much more seamless, and now the app.R file also includes icon for editing our Shiny UI with the shinyuieditor package (provided it’s installed).

Package Development

Transitioning from developing R packages in RStudio to Positron has been pretty smooth. For example, I wanted to change the display_type() function to check if the application runs in RStudio before setting the shiny.launch.browser option.¹²

Positron tab-completion

Positron also comes with IntelliSense for R functions. Place your cursor inside the parentheses and use ^+SPACE or tab:

Loading & Documenting

After making changes to R/display_type.R, I can use the same keyboard shortcuts from devtools to load and document the package:

Cmd / Ctrl + Shift + L = devtools::load_all()

Cmd / Ctrl + Shift + D = devtools::document()

Under the hood, Positron calls devtools::load_all() and devtools::document(), but instead of launching a Build pane, Positron displays the messages from in the Console:

Document R/display_type.R (click to enlarge)

The display_type.Rd in the Console is a hyperlink we can use to preview our updated help file.

Preview help file for R/display_type.R (click to enlarge)

Installing

Positron uses the same keyboard shortcut as RStudio for installing packages, but the underlying process differs slightly. Instead of calling devtools::install() in the Build pane, Positron launches the Terminal and runs pak::local_install(upgrade = FALSE):

Cmd / Ctrl + Shift + B = pak::local_install(upgrade = FALSE)

The new package install Terminal commands are bookended with an asterick (*) and a message (click to enlarge) — The new package install Terminal commands are bookended with an asterick (`*`) and a message (click to enlarge)

The Terminal pane displays a dedicated Install R package task when a package is installed.

local_install(upgrade = FALSE) updates the package with the minimum work needed, upgrading dependencies only if the package or one of its dependencies requires a higher version. It prefers binary packages to source packages, even if the binaries are older.

local_install() also seems to takes a bit longer to run than devtools::install(), but the end result is the same (i.e., the package is installed, the R session restarts, and the package is loaded with library() in the Console).

IntelliSense

In the Console, Positron’s tab completion and IntelliSense displays a large preview each function’s help file:

Testing

Positron comes with a variety of options for testing code. We can use the standard keyboard shortcut to call devtools::test(). This will open a Terminal task with the test results:¹³

Cmd / Ctrl + Shift + T = devtools::test()

Running devtools::test() (click to enlarge) — Running `devtools::test()` (click to enlarge)

Positron also has a dedicated testing sidebar menu item that allows us to select or filter the test files in the tests/testthat/ folder.

Test files in tests/testthat/ (click to enlarge) — Test files in `tests/testthat/` (click to enlarge)

The testing sidebar menu also displays the contents of each test file. If you’re using testthat’s behavior-driven development functions (describe and it), the descriptions are organized hierarchically under TESTING:

BDD test descriptions (click to enlarge)

If test_that() is used, the function being tested is displayed each time an expect_* function is called:

test_that() test descriptions (click to enlarge) — `test_that()` test descriptions (click to enlarge)

Running tests

The icon under the TESTING sidebar menu item can also be used to run all the tests in the testthat folder.

Package Development Keyboard Shortcuts

Two additional shortcuts I recommend adding are:

Cmd / Ctrl + T = devtools::test_active_file()

Cmd / Ctrl + Shift + R = devtools::test_coverage_active_file()

Check out Andrew Heiss’ Positron post for more information on changing keyboard shortcuts

Recap

Positron brings a refined experience for RStudio users, blending powerful tools in a streamlined layout that promotes an efficient workflow. Here’s a recap of the features we’ve explored:

IDE Layout: Positron’s design ensures smooth navigation. It focuses on customizable panels that allow developers to arrange code editors, data viewers, and debugging consoles based on their workflow.
Support for R & Python: The IDE accommodates multiple versions of R and Python, offering a consistent environment for both languages. Integrated version control helps manage and switch between environments seamlessly, making it ideal for teams working on cross-language projects.
Shiny App Development: Positron provides robust tools for developers to build, test, and deploy Shiny applications. The IDE simplifies UI-building with live previews and reactive programming support, enabling users to refine interactive components.
Package Development: Positron includes a comprehensive suite for R package development, with features that streamline code documentation, testing, and version management. These tools make it easier to follow best practices, ensuring well-organized, maintainable packages.

Positron can enhance productivity for R and Python users, making it a strong choice for data science and development.

Footnotes

I’m using version 2024.07.0-107 ↩︎
The Variables pane is similar to the Environments pane in RStudio.↩︎
These packages are described in the R prerequisites section.↩︎
sap is the Shiny app-package I used to demonstrate development in my Shiny-App-Packages book.↩︎
I’m using a branch from sap, which is a collection of Shiny apps/R packages.↩︎
Read more on Garrick’s blog ↩︎
The Open VXS Registry is manages by the Eclipse Foundation.↩︎
Read more on Andrew’s blog ↩︎
Read more on Veerle’s blog ↩︎
I’m demoing the 02.1_shiny-app, which is a boilerplate Shiny app project with the Old Faithful Geyser data.↩︎
Read more about Shiny development mode here.↩︎
This is covered in the 08_launch-app branch of moviesApp, which is covered in the Launch chapter of Shiny-App-Packages.↩︎
I’m demonstrating with the 12.3_tests-snapshots branch of sap, which is covered in the Test Tools chapter of Shiny-App-Packages.↩︎