Shiny Developer Mode — devmode • shiny

Developer Mode enables a number of options() to make a developer's life easier, like enabling non-minified JS and printing messages about deprecated functions and options.

Please see the function descriptions for more details.

devmode(
  devmode = getOption("shiny.devmode", TRUE),
  verbose = getOption("shiny.devmode.verbose", TRUE)
)

in_devmode()

with_devmode(devmode, code, verbose = getOption("shiny.devmode.verbose", TRUE))

devmode_inform(
  message,
  .frequency = "regularly",
  .frequency_id = message,
  .file = stderr(),
  ...
)

register_devmode_option(name, devmode_message = NULL, devmode_default = NULL)

get_devmode_option(
  name,
  default = NULL,
  devmode_default = missing_arg(),
  devmode_message = missing_arg()
)

Arguments

devmode	Logical value which should be set to `TRUE` to enable Shiny Developer Mode
verbose	Logical value which should be set to `TRUE` display Shiny Developer messages
code	Code to execute with the temporary Dev Mode options set
message	Developer Mode message to be sent to `rlang::inform()`
.frequency	Frequency of the Developer Mode message used with `rlang::inform()`. Defaults to once every 8 hours.
.frequency_id	`rlang::inform()` message identifier. Defaults to `message`.
.file	Output connection for `rlang::inform()`. Defaults to `stderr()`
...	Parameters passed to `rlang::inform()`
name	Name of option to look for in `options()`
devmode_message	Message to display once every 8 hours when utilizing the `devmode_default` value. If `devmode_message` is missing, the registered `devmode_message` value be used.
devmode_default	Default value to return if `in_devmode()` returns `TRUE`. For `get_devmode_option()`, if `devmode_default` is missing, the registered `devmode_default` value will be used.

Functions

devmode: Function to set two options to enable/disable Shiny Developer Mode and Developer messages
in_devmode: Determines if Shiny is in Developer Mode. If the getOption("shiny.devmode") is set to TRUE and not in testing inside testthat, then Shiny Developer Mode is enabled.
with_devmode: Temporarily set Shiny Developer Mode and Developer message verbosity
devmode_inform: If Shiny Developer Mode and verbosity are enabled, displays a message once every 8 hrs (by default)

register_devmode_option: Registers a Shiny Developer Mode option with an updated value and Developer message. This registration method allows package authors to write one message in a single location.

For example, the following Shiny Developer Mode options are registered:

# Reload the Shiny app when a sourced R file changes
register_devmode_option(
  "shiny.autoreload",
  "Turning on shiny autoreload. To disable, call `options(shiny.autoreload = FALSE)`",
  devmode_default = TRUE
)

# Use the unminified Shiny JavaScript file, `shiny.js`
register_devmode_option(
  "shiny.minified",
  "Using full shiny javascript file. To use the minified version, call `options(shiny.minified = TRUE)`",
  devmode_default = FALSE
)

# Display the full stack trace when errors occur during Shiny app execution
register_devmode_option(
  "shiny.fullstacktrace",
  "Turning on full stack trace. To disable, call `options(shiny.fullstacktrace = FALSE)`",
  devmode_default = TRUE
)

Other known, non-Shiny Developer Mode options:

Sass:

# Display the full stack trace when errors occur during Shiny app execution
register_devmode_option(
  "sass.cache",
  "Turning off sass cache. To use default caching, call `options(sass.cache = TRUE)`",
  devmode_default = FALSE
)

get_devmode_option: Provides a consistent way to change the expected getOption() behavior when Developer Mode is enabled. This method is very similar to getOption() where the globally set option takes precedence. See section "Avoiding direct dependency on shiny" for get_devmode_option() implementation details.

Package developers: Register your Dev Mode option using register_devmode_option() to avoid supplying the same devmode_default and devmode_message values throughout your package. (This requires a shiny dependency.)

Avoiding direct dependency on shiny

The methods explained in this help file act independently from the rest of Shiny but are included to provide blue prints for your own packages. If your package already has (or is willing to take) a dependency on Shiny, we recommend using the exported Shiny methods for consistent behavior. Note that if you use exported Shiny methods, it will cause the Shiny package to load. This may be undesirable if your code will be used in (for example) R Markdown documents that do not have a Shiny runtime (runtime: shiny).

If your package can not take a dependency on Shiny, we recommending re-implementing these two functions:

in_devmode():

This function should return TRUE if getOption("shiny.devmode") is set. In addition, we strongly recommend that it also checks to make sure testthat is not testing.
```
in_devmode <- function() {
  isTRUE(getOption("shiny.devmode", FALSE)) &&
    !identical(Sys.getenv("TESTTHAT"), "true")
}
```
get_devmode_option(name, default, devmode_default, devmode_message):

This function is similar to getOption(name, default), but when the option is not set, the default value changes depending on the Dev Mode. get_devmode_option() should be implemented as follows:
- If not in Dev Mode:
  - Return getOption(name, default).
- If in Dev Mode:
  - Get the global option getOption(name) value.
  - If the global option value is set:
    - Return the value.
  - If the global option value is not set:
    - Notify the developer that the Dev Mode default value will be used.
    - Return the Dev Mode default value.
When notifying the developer that the default value has changed, we strongly recommend displaying a message (devmode_message) to stderr() once every 8 hours using rlang::inform(). This will keep the author up to date as to which Dev Mode options are being altered. To allow developers a chance to disable Dev Mode messages, the message should be skipped if getOption("shiny.devmode.verbose", TRUE) is not TRUE.
```
get_devmode_option <- function(name, default = NULL, devmode_default, devmode_message) {
  if (!in_devmode()) {
    # Dev Mode disabled, act like `getOption()`
    return(getOption(name, default = default))
  }

  # Dev Mode enabled, update the default value for `getOption()`
  getOption(name, default = {
    # Notify developer
    if (
      !missing(devmode_message) &&
      !is.null(devmode_message) &&
      getOption("shiny.devmode.verbose", TRUE)
    ) {
      rlang::inform(
        message = devmode_message,
        .frequency = "regularly",
        .frequency_id = devmode_message,
        .file = stderr()
      )
    }

    # Return Dev Mode default value `devmode_default`
    devmode_default
  })
}
```

The remaining functions in this file are used for author convenience and are not recommended for all reimplementation situations.

Examples

# Enable Shiny Developer mode
devmode()

in_devmode() # TRUE/FALSE?
#> [1] TRUE

# Execute code in a temporary shiny dev mode
with_devmode(TRUE, in_devmode()) # TRUE
#> [1] TRUE

# Ex: Within shiny, we register the option "shiny.minified"
#   to default to `FALSE` when in Dev Mode
if (FALSE) register_devmode_option(
  "shiny.minified",
  devmode_message = paste0(
    "Using full shiny javascript file. ",
    "To use the minified version, call `options(shiny.minified = TRUE)`"
  ),
  devmode_default = FALSE
)

# Used within `shiny::runApp(launch.browser)`
get_devmode_option("shiny.minified", TRUE) # TRUE if Dev mode is off
#> shiny devmode - Using full shiny javascript file. To use the minified version, call `options(shiny.minified = TRUE)`
#> This message is displayed once every 8 hours.
#> [1] FALSE
is_minified <- with_devmode(TRUE, {
  get_devmode_option("shiny.minified", TRUE)
})
is_minified # FALSE
#> [1] FALSE