8 Launch

Published

2026-10-16

TLDR: Launch your app

Launching Apps:

shinyApp(): can be bundled in a standalone app function to store an app-package
- Also useful for quick prototyping or if an app is in a single .R script
- Returns a shiny app object (helpful with testing)
runApp(): versatile function that can launch apps in multiple formats/locations (blocking)
- A directory with a server.R and ui.R, or a single app.R file
- An app object created by shinyApp()
startApp(): launches app in background process, returns console control immediately (non-blocking)
- Best for interactive development and rapid iteration
- Requires specifying a port
- New as of v1.14.0!
shinyAppDir(): launches a Shiny app programmatically from a directory.

This chapter covers the differences between shinyApp(), runApp(), and shinyAppDir(), what should go in an app.R file, and other options for launching an app (or apps) from within an app-package.

Positron Version

At the time of this writing, the Positron version 1.130.0 was available.

During development, we have a variety of options for launching applications. Both RStudio and Positron offer a single-click button to run our application the top of the Source pane/Editor. We can also launch the app by calling the standalone app function in the Console. Below we’ll cover what happens behind the scenes when we click on these icons.

Access the applications in this chapter

I’ve created the shinypak R package in an effort to make each section accessible and easy to follow. Install shinypak using pak (or remotes):

install.packages('pak')
pak::pak('mjfrigaard/shinypak')
library(shinypak)

List the apps in this chapter:

list_apps(regex = '08')

Launch apps with launch()

launch(app = '08_launch')

Download apps with get_app()

get_app(app = '08_launch')

8.1 Running apps

In the current branch of sap, the app.R file contains a call to launch_app(), which loads the package and passes the UI and server functions to shinyApp().

‘Launch’ vs. ‘Run’

I’ll be using the term ‘launch’ to differentiate successfully displaying the application locally (either in the IDE window, viewer pane, or browser) from clicking on the Run App/Run Shiny App button or calling the runApp() function.

See the 06.2_pkg-imports branch of sap.

RStudio and Positron display Run App and Run Shiny App buttons respectively in the Source pane. Clicking either button calls runApp() and launches the application, but with a loadSupport() warning.

The section below will cover the loadSupport() warning and why it appears when using the Run App/Run Shiny App buttons in RStudio and Positron .

8.1.1 `loadSupport()` warnings

loadSupport() warning

The warning in the Console is telling us loadSupport() has detected that sap is a package, but it’s still sourcing the R/ subdirectory.¹

As noted above, clicking Run App in RStudio calls runApp() and launches our application with a loadSupport() warning printed in the Console.

Clicking Run App in RStudio calls runApp() and displays the loadSupport() warning — Clicking **Run App** in RStudio calls `runApp()` and displays the `loadSupport()` warning

In Positron , clicking on the Run Shiny App button launches the application with a slightly different process than RStudio :

Clicking Run Shiny App in Positron calls runApp() and displays the loadSupport() warning — Clicking **Run Shiny App** in Positron calls `runApp()` and displays the `loadSupport()` warning

A new Shiny terminal process is started with the --devmode option
runApp() is called with the full path to our app.R file and a port argument²
The loadSupport() warning is displayed in the Terminal

It’s important to note that we also see the loadSupport() warning if we bypass the Run App/Run Shiny App buttons and call shiny::runApp() directly in the Console:

Calling runApp() directly in RStudio’s Console displays the loadSupport() warning — Calling `runApp()` directly in RStudio’s **Console** displays the `loadSupport()` warning

Calling runApp() directly in Positron’s Console displays the loadSupport() warning — Calling `runApp()` directly in Positron’s **Console** displays the `loadSupport()` warning

What’s with the warning?

In the Shiny chapter we learned loadSupport() is called automatically when an application is run with runApp(). Specifically, loadSupport()

“loads any top-level supporting .R files in the R/ directory adjacent to the app.R/server.R/ui.R files” ³

Behind the scenes, runApp() is called by both Run App/Run Shiny App buttons, which then automatically calls loadSupport(). This is why if we pass our standalone app function to the Console (which uses shinyApp(), not runApp()), the warning disappears:

No loadSupport() warning in RStudio — No `loadSupport()` warning in RStudio

No loadSupport() warning in Positron — No `loadSupport()` warning in Positron

The examples above demonstrate the differences between calling shinyApp() and runApp(), and the tension between calling a standalone app function from an R package vs. sourcing the app.R file in a Shiny project.

8.1.2 `--devmode`

Clicking Run Shiny App in Positron launches the application in devmode, which controls how Shiny behaves during development. See Positron’s runShinyApp.R for the devmode launcher implementation.

8.2 Shiny launch functions

In the following sections, we’ll compare shinyApp(), shinyAppDir(), and runApp() to determine which one to use in R/launch_app.R and the app.R file. As we’ve seen, the Run App/Run Shiny App buttons call runApp(), even when we have a call to shinyApp() in the app.R file. This might make you wonder,

“Why even include a call to shinyApp() if the app is being launched with runApp()?”

Let’s review what happens when we call shinyApp().

8.2.1 `shinyApp()`

One of the key features of shinyApp() is the creation of the shiny.appobj (a shiny app object):

app <- shinyApp(ui = movies_ui, 
                server = movies_server)
str(app)

If we look at the structure of the returned object from shinyApp(), we see the shiny.appobj includes the appDir under appOptions:

List of 5
 $ httpHandler     :function (req)  
 $ serverFuncSource:function ()  
 $ onStart         : NULL
 $ options         : list()
 $ appOptions      :List of 2
  ..$ appDir       : chr "/path/to/sap"
  ..$ bookmarkStore: NULL
 - attr(*, "class")= chr "shiny.appobj"

1: appDir is the first argument of runApp()
2: A shiny app object

This is why runApp() works with any .R file creating a shiny app object.

shinyApp()

shinyApp(): Creates and launches an app defined inline within the call itself (or with UI and server functions passed as arguments).

shinyApp(
  ui = fluidPage(
    # UI elements
  ),
  server = function(input, output) {
    # Server logic
  }
)

8.2.2 `shinyAppDir()`

shinyAppDir() is similar to shinyApp(), but is designed to use a “path to directory that contains a Shiny app.”

In practice, we can use shinyAppDir() with a returned object from shinyApp():

app <- shinyApp(
        ui = movies_ui,
        server = movies_server
      )
app$appOptions$appDir

[1] "path/to/sap"

This path can be passed to the appDir argument (along with any Shiny options).

shinyAppDir(
  appDir = app$appOptions$appDir,
  options(test.mode = TRUE)
)

shinyAppDir()

shinyAppDir(): Launches an app from a directory (with an app.R or ui.R/server.R files).

shinyAppDir(
  appDir = "path/to/app/", 
  options = list())

8.2.3 `runApp()`

The reason we’re able to call runApp() in the Console to launch both applications above is because it’s very versatile:

`runApp()`

Can launch apps from ui.R/server.R, app.R or directory:

# In console
runApp()

Works with a path to an .R file that creates a shiny.appobj:⁴

runApp(appDir = "path/to/sap")

Can also use a shiny.appobj directly:

app <- shinyApp(
        ui = movies_ui,
        server = movies_server)
runApp(appDir = app)

This final method does not produce the loadSupport() warning because a Shiny object (shiny.appobj) has already been created, and runApp() is essentially calling print(app) in the Console.

runApp()

runApp(): A generalized way to launch your app–it can run apps defined inline, or from a directory.

runApp(
  appDir = "path/to/app/",
  test.mode = TRUE/FALSE)

8.2.4 `startApp()`

Shiny recently introduced startApp(), which changes how we think about launching apps interactively. While runApp() blocks the R session (you cannot type in the console while the app is running), startApp() launches the app in the background and returns control to the console immediately.

I’ve found this matters most when you’re exploring your app interactively. Instead of restarting R each time you want to test a change, you can modify your code and re-run it while the app is still running in another process. The app stays live and you keep your REPL.

Below are some practical examples for using startApp():

Launch and stop a shiny app object:

app <- startApp(
  appDir = shinyApp(
    ui = movies_ui(),
    server = movies_server),
  port = 3838
)
app$stop()

Launch with test mode enabled:

app <- startApp(
  appDir = shinyApp(
    ui = movies_ui(),
    server = movies_server,
    options = list(test.mode = TRUE)
  ),
  port = 3838,
  test.mode = TRUE
)

Check app status and URL:

app <- startApp(
  appDir = shinyApp(
    ui = movies_ui(),
    server = movies_server
  ),
  port = 3838
)
app$status()
app$url()

After the app launches, you keep your console and can continue working: run tests, modify code, re-source functions, or launch additional apps on different ports. Call handle$stop() to stop the background app when you’re done.

The key difference is simple: runApp() is blocking and single-process. startApp() is non-blocking and spawns a background process. When to use startApp() vs. runApp(): I recommend startApp() for interactive development (you need console access), and runApp() for traditional deployment (the blocking behavior is fine). In production or when you’re ready to fully focus on the running app, runApp() is still the right choice. But for rapid iteration in development, startApp() unlocks a faster workflow.

See the Shiny documentation for full details on startApp() arguments and capabilities.

startApp()

startApp(): Launches your app in a background process and returns console control immediately (non-blocking).

startApp(
  appDir = shinyApp(...),
  port = 3838)

Recap

shinyApp() is typically used to create apps within an interactive R session
shinyAppDir() runs a Shiny app stored in a directory (containing an app.R file (or ui.R and server.R files)
runApp() also launches apps in a directory, but it’s versatility makes it suitable for running apps in various formats, either defined inline or in separate directories.⁵
startApp() launches an app in a background process and returns console control immediately, making it ideal for interactive development and rapid iteration.

8.3 Standalone function

I tend to name the standalone app function launch_app() and include the options covered below (none of these are required, though).

Launch app with the shinypak package:

launch('08_launch')

8.3.1 App launching options

shinyApp() or shinyAppDir() both have an options argument, so we should make this available in launch_app(). For example, one of the Shiny options we could include in our standalone app function is test.mode:

‘Should the application be launched in test mode? This is only used for recording or running automated tests. Defaults to the shiny.testmode option, or FALSE if the option is not set.’

The test.mode option lets us export values from our application when we’re running tests (which we’ll cover in-depth in the Tests section).

We’ll make options an argument that defaults to an empty list() in launch_app():

launch_app <- function(options = list()) {
    shinyApp(
      ui = movies_ui(),
      server = movies_server,
      options = options
      )
}

1: Build the shiny app object with movies_ui and movies_server
2: Include options list

With the introduction of startApp(), we can add a mode argument to choose between blocking ("run") and non-blocking ("start") execution:

launch_app <- function(options = list(), mode = "run", run = "p") {
  app <- shinyApp(
    ui = movies_ui(),
    server = movies_server,
    options = options
  )

  if (mode == "start") {
    shiny::startApp(appDir = app, port = 3838)
  } else if (mode == "run") {
    display_type(run = run)
    shiny::runApp(appDir = app)
  }
}

1: Create the shiny app object
2: Non-blocking mode—launches in background process
3: Blocking mode (default)—uses display_type() for window placement

Now you can call launch_app(mode = "start") for rapid iteration or launch_app(mode = "run") for traditional blocking execution.

8.3.2 Where to launch?

I’ve written a display_type() helper function to 1) check if the application is being run in RStudio and, if so, 2) control where the Shiny app is launched. The run argument in display_type() takes the following options:

"p" = Viewer Pane
"w" = IDE Window
"b" = External browser

The option to access configuration is shiny.launch.browser:⁶

#' Shiny app display mode helper
#'
#' @param run where to launch app: 
#'  * `"p"` = launch in viewer pane 
#'  * `"b"` = launch in external browser  
#'  * `"w"` = launch in window (default)
#'
#' @return notification of `shinyViewerType` option
#' 
#' @export
#'
display_type <- function(run = "w") {
  if (interactive()) {
    if (Sys.getenv("RSTUDIO") == "1") {
      
      switch(
        run,
        p = options(shiny.launch.browser = .rs.invokeShinyPaneViewer),
        b = options(shiny.launch.browser = .rs.invokeShinyWindowExternal),
        w = options(shiny.launch.browser = .rs.invokeShinyWindowViewer),
        NULL = options(shiny.launch.browser = NULL)
      )
      environment <- "RStudio"
      shinyViewerType <- getOption('shiny.launch.browser') |>
        attributes() |>
        unlist() |>
        unname()
      
      cli::cli_alert_info("App running in {environment}")
      cli::cli_alert_info("shinyViewerType set to {shinyViewerType}")
    } else {
      environment <- "RStudio"
      cli::cli_alert_info("App not running in {environment}")
    }
  } else {
    cli::cli_alert_info("App not running in interactive session")
  }
}

1: Detect IDE
2: Set option
3: Print IDE
4: Print option

New dependency!

The cli package is imported as part the devtools/usethis workflow but we want to add it the Imports field of the DESCRIPTION with usethis::use_package('cli').

8.3.3 An updated `launch_app()`

The display_type(), options list, and mode argument have been added to launch_app():

launch_app <- function(options = list(), mode = "run", run = "p") {
    app <- shinyApp(
      ui = movies_ui(),
      server = movies_server,
      options = options
    )

    if (mode == "start") {
      shiny::startApp(appDir = app, port = 3838)
    } else if (mode == "run") {
      display_type(run = run)
      shiny::runApp(appDir = app)
    }
}

1: Create the shiny app object
2: Non-blocking mode—launches app in background, returns console control
3: Blocking mode (default)—uses display_type() for window placement, blocks console

After loading, documenting, and installing our package, we can see the documentation for our updated launch_app() function in RStudio and Positron :

Ctrl/Cmd + Shift + L
Ctrl/Cmd + Shift + D
Ctrl/Cmd + Shift + B

In RStudio , we will confirm the app is launching without the loadSupport() warning, the message is printing to the Console from the run argument, and test.mode are implemented correctly.

We also want to confirm launch_app() works in Positron :

launch_app() launches the app in the Window — `launch_app()` launches the app in the Window

The updated launch_app() function launches the application in the Viewer — The updated `launch_app()` function launches the application in the Viewer

The updated launch_app() function in Positron — The updated `launch_app()` function in Positron

When we’re confident our standalone app function is working, we’ll write the app.R file.

8.4 The `app.R` file

The app.R file should contain any options or settings that we would use during development. There are multiple ways to launch an application from app.R, so I encourage you to explore the options below to find a method that works for your workflow/environment.

8.4.1 Is this an interactive session?

The first condition we’ll check to see if there is a “human operator to interact with” with base::interactive():

if (!interactive()) {
  
} else {
   
}

You have probably seen control flow like this in shiny help file examples (like flowLayout() below):

(a) `if (interactive())` in `flowLayout()` example

Adding if and interactive() will allow our app.R file distinguish between 1) launching apps from a RStudio/Positron session (i.e., during development) and 2) deploying apps (i.e., like publishing the application on Posit Connect).

8.4.1.1 Non-interactive sessions

If the session is non-interactive, we’ll divert all regular output to the standard error stream. The sink() function “diverts R output to a connection”, so the code below sends the output that would normally print to the console to the where error messages are written.

if (!interactive()) {
   sink(stderr(), type = "output")
} else {
   
}

This is useful in a non-interactive settings if we want to re-direct the error output for the console text-mode connection.

tryCatch() is used for ‘catching conditions’ during the execution of an expression (expr =):

if (!interactive()) {
   sink(stderr(), type = "output")
   tryCatch(expr = {
      library(sap)
   }, error = function(e) {
      pkgload::load_all()
   })
} else {
   
}

In this case, if library(sap) throws an error, the function specified after error = is executed (i.e., pkgload::load_all()).⁷

Written this way, in a non-interactive R session, app.R will re-direct the error output and attempt to load and attach sap, and if this fails, app.R will attempt to load all the files in the R/ folder.

8.4.1.2 Interactive sessions

If the session is interactive, we want app.R to load all the code in the R/ folder with pkgload::load_all() before launching our app with launch_app() (and a few optional arguments).

if (!interactive()) {
  sink(stderr(), type = "output")
  tryCatch(
    expr = {
      library(sap)
    },
    error = function(e) {
      pkgload::load_all()
    }
  )
} else {
  pkgload::load_all()
}
  sap::launch_app(
    options = list(test.mode = TRUE), mode = "run", run = 'p')

pkgload::load_all() is the function that’s called when we run devtools::load_all() (or use Ctrl/Cmd + Shift + L), and this is somewhat analogous to running library(sap)

New dependency!

The pkgload package is imported as part the devtools/usethis workflow, otherwise we’d want to add it the Imports field of the DESCRIPTION with usethis::use_package('pkgload').

8.4.1.3 Dealing with `loadSupport()`

The withr package is designed to ‘run code with safely and temporarily modified global state’, and it comes in handy when launching shiny apps. For example, I want to turn off the loadSupport() behavior when launching the app from app.R.⁸

We can use withr::with_options() to accomplish this using the following new and code arguments

new: a named list of the new options and their values
code: the ’Code to execute in the temporary environment

We’ll place the withr::with_options() at the top of app.R and pass shiny.autoload.r = FALSE to the new argument (the contents of our app.R are passed into the code argument).

withr::with_options(new = list(shiny.autoload.r = FALSE), code = {
  if (!interactive()) {
    sink(stderr(), type = "output")
    tryCatch(
      expr = {
        library(sap)
      },
      error = function(e) {
        pkgload::load_all()
      }
    )
  } else {
    pkgload::load_all()
  }
    sap::launch_app(
      options = list(test.mode = TRUE), mode = "run", run = 'p')
})

1: Turn off loadSupport()
2: Define non-interactive behaviors
3: Define interactive behaviors
4: Launch app (with options)

Now that we’ve updated the app.R to account for the app-package structure, we’ll load, document, and install sap and send it’s contents to the Console:

Ctrl/Cmd + Shift + L
Ctrl/Cmd + Shift + D
Ctrl/Cmd + Shift + B

New dependency!

The withr package is imported as part the devtools/usethis workflow, otherwise we’d want to add it the Imports field of the DESCRIPTION with usethis::use_package('withr').

8.4.2 Updated `app.R`

When we send the contents of app.R to the Console, the loadSupport() options are applied before running the app:

Sending app.R to RStudio’s Console — Sending `app.R` to RStudio’s **Console**

Sending app.R to Positron’s Console — Sending `app.R` to Positron’s **Console**

R/_disable_autoload.R

In the documentation for loadSupport(), you’ll find a second option for removing the R/ directory sourcing behavior: placing a _disable_autoload.R file in the R/ directory (this is also one of the behaviors of the golem framework, which we will cover in the following chapters).

Both methods work–this chapter demonstrates a way to remove the loadSupport() warning without having to add this file.

Recap

This chapter has covered some options for launching your app within your app-package. We went over what to include in the standalone app function and the app.R file, the differences between shinyApp(), shinyAppDir() and runApp(), but it’s worth exploring these topics further (especially if you plan on having more than one apps in your package).

Recap: launching your app

shinyApp():

shinyApp() doesn’t care about file structure, so it’s useful for quick prototyping or if the app is in a single .R script. It’s also more portable because you can share your app with a single .R script.
- It’s possible to bundle shinyApp() in a wrapper function to integrate within an R package (like we’ve done with launch_app()).
- shinyApp() returns a shiny app object, which can be useful if you want to explore the app structure programmatically (i.e., testing).

shinyAppDir():

shinyAppDir() launches an app from a directory, and is useful if an app is spread across multiple files and folders.

runApp() (blocking):

runApp() is a more generalized way to launch an app. It works with:
- apps contained in a directory (i.e., runApp('path/to/app'))
- apps in separate ui.R and server.R files (or a single app.R file)
- a shiny app object (passed to the appDir argument).
Clicking on Run App will run the application with runApp() if it detects a file (or files) that creates a shiny object.
Blocks the console during execution (you cannot type while the app runs).

startApp() (non-blocking):

startApp() launches your app in a background process and returns console control immediately.
Best for interactive development and rapid iteration—modify code and re-run without restarting R.
Requires specifying a port for the background app process.
Not recommended for production deployments where runApp() is the standard approach.

In the following chapter, we’re going to cover where to put non-standard R package files that are common to Shiny apps (images, .css/.scss file, etc.).

See a typo, error, or something missing?

Please open an issue on GitHub

If you recall, we covered the loadSupport() function in Chapter 2.↩︎
I’ve displayed the application in the browser clicking on the ‘Open the current URL in the default browser’ icon.↩︎
loadSupport() does this by sourcing the files in alphabetical order.↩︎
Shiny’s examples are run using runApp()↩︎
It’s worthwhile to read the documentation on shinyApp(), shinyAppDir(), runApp(), and startApp().↩︎
The shiny.launch.browser options are covered in this blog post by Garrick Aden-Buie, and I’ve combined them into a run argument in launch_app()↩︎
pkgload is part of the conscious uncoupling of the devtools package we learned about back in Chapter 6.↩︎
You can read more about the shiny.autoload.r option and loadSupport() in this article ↩︎

8.1 Running apps

8.1.1 loadSupport() warnings

8.1.2 --devmode

8.2 Shiny launch functions

8.2.1 shinyApp()

8.2.2 shinyAppDir()

8.2.3 runApp()

runApp()

8.2.4 startApp()

Recap

8.3 Standalone function

8.3.1 App launching options

8.3.2 Where to launch?

8.3.3 An updated launch_app()

8.4 The app.R file

8.4.1 Is this an interactive session?

8.4.1.1 Non-interactive sessions

8.4.1.2 Interactive sessions

8.4.1.3 Dealing with loadSupport()

8.4.2 Updated app.R

Recap

8.1.1 `loadSupport()` warnings

8.1.2 `--devmode`

8.2.1 `shinyApp()`

8.2.2 `shinyAppDir()`

8.2.3 `runApp()`

`runApp()`

8.2.4 `startApp()`

8.3.3 An updated `launch_app()`

8.4 The `app.R` file

8.4.1.3 Dealing with `loadSupport()`

8.4.2 Updated `app.R`