run: Run a Shiny document

In rmarkdown: Dynamic Documents for R

Run a Shiny document

Description

Start a Shiny server for the given document, and render it for display.

Usage

run(
  file = "index.Rmd",
  dir = dirname(file),
  default_file = NULL,
  auto_reload = TRUE,
  shiny_args = NULL,
  render_args = NULL
)

Arguments

file	Path to the R Markdown document to launch in a web browser. Defaults to index.Rmd in the current working directory, but may be NULL to skip launching a browser.
dir	The directory from which to to read input documents. Defaults to the parent directory of file.
default_file	The file to serve at the Shiny server's root URL. If NULL (the default), a sensible default is chosen (see Details)
auto_reload	If TRUE (the default), automatically reload the Shiny application when the file currently being viewed is changed on disk.
shiny_args	Additional arguments to runApp.
render_args	Additional arguments to render.

Details

The run function runs a Shiny document by starting a Shiny server associated with the document. The shiny_args parameter can be used to configure the server; see the runApp documentation for details.

Once the server is started, the document will be rendered using render. The server will initiate a render of the document whenever necessary, so it is not necessary to call run every time the document changes: if auto_reload is TRUE, saving the document will trigger a render. You can also manually trigger a render by reloading the document in a Web browser.

The server will render any R Markdown (.Rmd) document in dir; the file argument specifies only the initial document to be rendered and viewed. You can therefore link to other documents in the directory using standard Markdown syntax, e.g. [Analysis Page 2](page2.Rmd).

If default_file is not specified, nor is a file specified on the URL, then the default document to serve at / is chosen from (in order of preference):

• If dir contains only one Rmd, that Rmd.

• The file ‘index.Rmd’, if it exists in dir.

• The first Rmd that has runtime: shiny in its YAML metadata.

• The file ‘index.html’ (or ‘index.htm’), if it exists in dir.

If you wish to share R code between your documents, place it in a file named global.R in dir; it will be sourced into the global environment.

Value

Invisible NULL.

Note

Unlike render, run does not render the document to a file on disk. In most cases a Web browser will be started automatically to view the document; see launch.browser in the runApp documentation for details.

When using an external web browser with the server, specify the name of the R Markdown file to view in the URL (e.g. http://127.0.0.1:1234/foo.Rmd). A URL without a filename will show the default_file as described above.

Examples

## Not run: 
# Run the Shiny document "index.Rmd" in the current directory
rmarkdown::run()

# Run the Shiny document "shiny_doc.Rmd" on port 8241
rmarkdown::run("shiny_doc.Rmd", shiny_args = list(port = 8241))

## End(Not run)

rmarkdown documentation built on Nov. 5, 2025, 7:35 p.m.