devmode: Shiny Developer Mode

Description

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.

Shiny Developer Mode can be enabled by calling devmode(TRUE) and disabled by calling devmode(FALSE).

Please see the function descriptions for more details.

Usage

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 and the specified option is not set in options(). For get_devmode_option(), if devmode_default is missing, the registered devmode_default value will be used.
default: Default value to return if in_devmode() returns TRUE and the specified option is not set in options().

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

Run this code

# Enable Shiny Developer mode
devmode()

in_devmode() # TRUE/FALSE?

# Execute code in a temporary shiny dev mode
with_devmode(TRUE, in_devmode()) # 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
is_minified <- with_devmode(TRUE, {
  get_devmode_option("shiny.minified", TRUE)
})
is_minified # FALSE

Run the code above in your browser using DataLab