README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# shinyenv

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/shinyenv)](https://CRAN.R-project.org/package=shinyenv)
[![Codecov test coverage](https://codecov.io/gh/shinyworks/shinyenv/branch/main/graph/badge.svg)](https://app.codecov.io/gh/shinyworks/shinyenv?branch=main)
[![R-CMD-check](https://github.com/shinyworks/shinyenv/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/shinyworks/shinyenv/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

An experimental package to deal with environment-like variables in Shiny.

## Installation

You can install the development version of shinyenv from [GitHub](https://github.com/) with:

```{r eval = FALSE}
# install.packages("pak")
pak::pak("shinyworks/shinyenv")
```

Alternatively, you can use the functions without taking a dependency on {shinyenv}:

```{r eval = FALSE}
# install.packages("usethis")
usethis::use_standalone("shinyworks/shinyenv", "envvars")
```

## Usage

### You probably shouldn't use this package.

> You might see advice to use `session$userData` or other techniques to break out of the module straitjacket. Be wary of such advice: it’s showing you how to work around the rules imposed by namespacing, making it easy to re-introduce much complexity to your app and significantly reducing the benefits of using a module in the first place.  
> -- Hadley Wickham, <cite>[Mastering Shiny](https://mastering-shiny.org/scaling-modules.html#inputs-and-outputs)</cite>

You should almost always use Shiny's built-in mechanisms for setting and accessing variables.
I highly recommend reading [Mastering Shiny](https://mastering-shiny.org/) to be certain that you actually need this type of variable before using the options presented here.

Shiny variables can be roughly divided into three categories:

-   **App-wide variables that apply to all users:** Use normal R variables, options (`getOption()`), and/or environment variables (`Sys.getenv()`).
-   **Variables that apply to a single user:** Almost always use Shiny's `reactiveValues()`, `reactiveVal()`, `reactive()`, the `input` system, and/or return values from modules.
-   **Variables that apply to a single user, are shared across multiple modules, and can be updated in multiple places:** Use this package. These should be places where, in a non-Shiny context, you would use `Sys.setenv()` to set a variable (for yourself) and `Sys.getenv()` to get it.

### But if you're sure you want to...

Instead of `Sys.setenv()`, use `shinyenv::shiny_setenv()`,

```{r eval = FALSE}
# NO: Sys.setenv(foo = "bar", baz = "foo")
shinyenv::shiny_setenv(foo = "bar", baz = "foo")
```

Instead of `Sys.getenv()`, use `shinyenv::shiny_getenv()`,

```{r eval = FALSE}
# NO: Sys.getenv("foo")
shinyenv::shiny_getenv("foo")
```

## Code of Conduct

Please note that the shinyenv project is released with a [Contributor Code of Conduct](https://shinyworks.github.io/shinyenv/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.