whole_game.qmd

# Whole app game {#sec-whole-game}

```{r}
#| eval: true 
#| echo: false 
#| include: false
source("_common.R")
```


```{r}
#| label: shinypak_apps
#| echo: false
#| results: asis
#| eval: true
shinypak_apps(regex = "01", branch = "01_whole-app-game")
```

This chapter is modeled on the [Whole Game chapter](https://r-pkgs.org/whole-game.html) in [R Packages, 2ed](https://r-pkgs.org).[^demo-monthApp] We’ll go through the development of the `monthAppPkg` Shiny app-package (adapted from [Mastering Shiny](https://mastering-shiny.org/scaling-packaging.html)).[^whole-game-month-app]  

[^demo-monthApp]: The [example app](https://github.com/hadley/monthApp) comes from the [Packages chapter of Mastering Shiny](https://mastering-shiny.org/scaling-packaging.html)

[^whole-game-month-app]: I've stored the code for this application in the [`01_whole-app-game`](https://github.com/mjfrigaard/sap) branch of the `sap` repository (to avoid confusing it with the *actual* application repo for this chapter).

## A toy app-package

We will briefly discuss creating an R package with a Shiny application. Each topic will be explained in detail in the next chapters. In the end, you will have a Shiny application with all the features and functions of an R package.

## Package metadata {#sec-use-description}

Every R package requires a `DESCRIPTION` file. You can quickly create one using `usethis::use_description()`.[^whole-game-use-desc] 

[^whole-game-use-desc]: The [Whole Game](https://r-pkgs.org/whole-game.html) chapter of R Packages, 2ed begins with the `usethis::create_package()` function, which calls `usethis::use_description()` internally. 

```{r}
#| eval: false
#| code-fold: false
usethis::use_description(
  fields = list(
    Package = 'monthAppPkg',
    Title = 'An example app-pkg',
    Version = '0.0.0.9000',
    Description = 'A shiny application built inside an R package.',
    "Authors@R" = NULL,
    Author = utils::person(
      given = "Jane",
      family = "Doe",
      role = c("aut", "cre")
    ),
    Maintainer = utils::person(
      given = "Jane",
      family = "Doe",
      email = "Jane.Doeh@email.io"
    ),
    License = "GPL-3"
  )
)
```

The values above in the `fields` list avoids the boilerplate content from `use_description()`.[^use-description-boilerplate] 

The essential seven fields are shown below:[^use-description-fields]

``` sh
Package: monthAppPkg
Title: An example app-pkg
Version: 0.0.0.9000
Author: Jane Doe [aut, cre]
Maintainer: Jane Doe <Jane.Doeh@email.io>
Description: A shiny application built inside an R package.
License: GPL-3

```

You will get specific fields automatically for function documentation and dependency management.[^desc-empty-line]

[^desc-empty-line]: Always leave an empty final line in the `DESCRIPTION`.

[^use-description-fields]: If you frequently develop R packages or Shiny apps, consider adding these fields to your `.Rprofile`. 

[^use-description-boilerplate]: At the time this was written, there are over [4,000 hits](https://github.com/search?q=%22description%3A+what+the+package+does%22&type=code) with the boilerplate value for `Description` (i.e., `"What the package does"`), which is a sign of how much `usethis` has been adopted (and how often people forget to come back and edit their `DESCRIPTION` file).

``` sh
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.3
```

## Data {#sec-use-data}

To include the `birthstones.csv` data in `monthAppPkg`, we'll create a `data-raw/` folder with `usethis::use_data_raw("stones")`.  Next, we'll move the `birthstones.csv` file into `data-raw/`, load it into the Global Environment, and an R package data object witho `usethis::use_data()`:

```{r}
#| eval: false
#| code-fold: false
usethis::use_data_raw("stones")
```

```{verbatim}
✔ Setting active project to '/path/to/monthAppPkg'
✔ Creating 'data-raw/'
✔ Adding '^data-raw$' to '.Rbuildignore'
✔ Writing 'data-raw/stones.R'
• Modify 'data-raw/stones.R'
• Finish the data preparation script in 'data-raw/stones.R'
• Use `usethis::use_data()` to add prepared data to package
```

Move `birthstones.csv` to `data-raw/birthstones.csv`:

```{r}
#| eval: false
#| code-fold: false
fs::file_move(path = "birthstones.csv", new_path = "data-raw/birthstones.csv")
```

Contents of `data-raw/stones.R`:

```{r}
#| eval: false
#| code-fold: false
## code to prepare `stones` dataset goes here
library(vroom)
stones <- vroom::vroom("data-raw/birthstones.csv")
usethis::use_data(stones, overwrite = TRUE)
```

```{verbatim}
#| eval: false
#| code-fold: false
Rows: 12 Columns: 2                                                                                                                                
── Column specification ──────────────────────────────────────────────────
Delimiter: ","
chr (2): month, stone

ℹ Use `spec()` to retrieve the full column specification for this data.
ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
```

```{r}
#| eval: false
#| code-fold: false
usethis::use_data(stones)
```

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding 'R' to Depends field in DESCRIPTION
✔ Setting LazyData to 'true' in 'DESCRIPTION'
✔ Saving 'stones' to 'data/stones.rda'
• Document your data (see 'https://r-pkgs.org/data.html')
```

Data should be documented using `roxygen2` which we’ll cover in the data chapter.[^whole-game-data-doc]

[^whole-game-data-doc]: View the documented `stones` dataset [here on GitHub](https://github.com/mjfrigaard/monthAppPkg/blob/main/R/data.R). 

## Dependencies {#sec-use-dependencies}

Every Shiny app-package depends on the `shiny` package. `usethis::use_package()`[^whole-game-use-pkg] adds it under the `Imports` field the `DESCRIPTION` file.

[^whole-game-use-pkg]: Whenever you use a function from another package, start by running `usethis::use_package()` to ensure it's in the `DESCRIPTION` file.

```{r}
#| eval: false
#| code-fold: false
usethis::use_package("shiny")
```

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding 'shiny' to Imports field in DESCRIPTION
• Refer to functions with `shiny::fun()`
```

We're advised to use explicit namespacing (i.e., `pkg::fun()`), but we can avoid this by importing all Shiny's functions into our package namespace using the `@import` tag from `roxygen2`.[^whole-game-import]

[^whole-game-import]: I've included `@import shiny` above the definition of our standalone app function (`R/launch_app.R`), which means I don't need to add `shiny::` when using Shiny functions below` R/`.


## Package code {#sec-use-r-code}

Create new `.R` files under `R/` using `use_r()`:

```{r}
#| eval: false
#| code-fold: false
usethis::use_r("monthFeedback")
```

```{verbatim}
#| eval: false
#| code-fold: false
✔ Setting active project to '/projects/apps/monthAppPkg'
• Modify 'R/monthFeedback.R'
```

Both UI and server module functions are stored in `R/monthFeedback.R` and `R/birthstone.R`. Tests should also be created for each function.

## Loading {#sec-use-load-all}

Shiny app development typically involves something like the following workflow: 

1. Write UI/server code  
2. Click **Run App**  
3. Rinse, repeat

When making the switch from app development to *app-package* development, calling `load_all()` is somewhat analogous to clicking on the **Run App** icon--you'll do it often (more than any other `devtools` or `usethis` function).

```{r}
#| eval: false
#| code-fold: false
devtools::load_all()
```

The output we're looking for from `load_all()` is straightforward:

```{verbatim}
#| eval: false
#| code-fold: false
ℹ Loading monthAppPkg
```

`load_all()` is similar to calling `library`, but it's specifically designed to be used during package development. Imagine sourcing all the functions in the `R/` folder, but more sophisticated.

## Package tests {#sec-use-package-tests}

Create tests for the code in the `R/` folder using `use_test()`

```{r}
#| eval: false
#| code-fold: false
usethis::use_test("monthFeedbackServer")
```

This will add `test-` files in `tests/testthat/`:

```{bash}
#| eval: false
#| code-fold: false
tests/
├── testthat/
│   └── test-monthFeedbackServer.R
└── testthat.R

2 directories, 2 files
```

The first time you run `use_test()`, it will detect if your package has the `testthat` infrastructure (and create the necessary files if you don't).[^whole-game-use_testthat] `use_test()` will also adds the `testthat` package to the `Suggests` field in the `DESCRIPTION` and includes the edition (currently `3`).

[^whole-game-use_testthat]: You can also set up the `testthat` infrastructure by calling `usethis::use_testthat()`


```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding 'testthat' to Suggests field in DESCRIPTION
✔ Adding '3' to Config/testthat/edition
```

Tests are covered in Mastering Shiny,[^whole-game-tests-ms] on the Shiny website,[^whole-game-tests-test-server] and in various testing packages (like `shinytest`[^whole-game-tests-shinytest] and `shinytest2`[^whole-game-tests-shinytest2]). 


[^whole-game-tests-ms]: The [Testing chapter](https://mastering-shiny.org/scaling-testing.html) in Mastering Shiny covers [unit tests](https://mastering-shiny.org/scaling-testing.html#testing-functions) with `testthat`, [`shiny::testServer()`](https://mastering-shiny.org/scaling-testing.html#testing-reactivity), and the [`shinytest` package](https://mastering-shiny.org/scaling-testing.html#testing-javascript). 

[^whole-game-tests-test-server]: See the '[Server Function Testing](https://shiny.posit.co/r/articles/improve/server-function-testing/)' article on the Shiny website for more information on `testServer()`

[^whole-game-tests-shinytest]: Check the `shinytest` [package website](https://rstudio.github.io/shinytest/articles/shinytest.html) and [video tutorial](https://posit.co/resources/videos/testing-shiny-applications-with-shinytest-shiny-developers-now-have-tools-for-automated-testing-of-complete-applications/) for more information on testing your app. 

[^whole-game-tests-shinytest2]: [`shinytest2`](https://rstudio.github.io/shinytest2/) is an updated verison of `shinytest` with [excellent documentation](https://rstudio.github.io/shinytest2/articles/in-depth.html) and [videos.](https://www.youtube.com/watch?v=Gucwz865aqQ) 

## app.R {#sec-use-app-dot-r}

The contents of `app.R` have been changed to include a call to `pkgload::load_all()` the standalone app function (`monthApp()`), which is stored in the `R/` folder. 

```{r}
#| eval: false
#| code-fold: false
pkgload::load_all(".")
monthApp()
```

`pkgload` needs to be listed under `Imports` in the `DESCRIPTION` file (just like we did with `shiny` above). 

```{r}
#| eval: false
#| code-fold: false
usethis::use_package("pkgload")
```

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding 'pkgload' to Imports field in DESCRIPTION
• Refer to functions with `pkgload::fun()`
```

Because we're only going to use `load_all()` from `pkgload`, we'll use explicit namespacing (i.e., `pkg::fun()`).[^whole-game-pkgload]

[^whole-game-pkgload]: We typically call `devtools::load_all()`, but using [`pkgload` ](https://pkgload.r-lib.org/) reduces the number of dependencies included with `devtools`. Read more about `pkgload` in the ['Conscious uncoupling' of `devtools`](https://github.com/r-lib/devtools#conscious-uncoupling). 

### use_package_doc() {#sec-use-pkg-doc-file}

The `use_package_doc()` creates the `R/[[name]-package].R` file, which can be used as a single location for declaring dependencies in `monthAppPkg`: 

```{r}
#| eval: false
#| code-fold: false
usethis::use_package_doc()
```

```{verbatim}
#| eval: false
#| code-fold: false
✔ Setting active project to 'projects/apps/monthAppPkg'
✔ Writing 'R/monthAppPkg-package.R'
• Modify 'R/monthAppPkg-package.R'
```

We'll use `@importFrom` to add *only* the `load_all()` function to the `NAMESPACE`.

```{r}
#| eval: false
#| code-fold: false
#' @keywords internal
"_PACKAGE"

## usethis namespace: start
#' @importFrom pkgload load_all
## usethis namespace: end
NULL
```

### use_build_ignore() {#sec-use-build-ignore}

R packages don't typically have an `app.R` file in their root folder, so we'll let `devtools` know this file should be ignored by creating a `.Rbuildignore` and include a pattern that excludes `app.R` whenever the package is built.

```{r}
#| eval: false
#| code-fold: false
usethis::use_build_ignore("app.R")
```

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding '^app\\.R$' to '.Rbuildignore'
```

It's best to let `use_build_ignore()` handle excluding any files or folders from your package builds because it automatically writes the correct regular expression pattern. 

## LICENSE {#sec-use-license-file}

Use one of the [`usethis` license functions](https://usethis.r-lib.org/reference/licenses.html) to add a `LICENSE` file. 

```{r}
#| eval: false
#| code-fold: false
usethis::use_mit_license()
```

The license file should match the `License` field in the `DESCRIPTION` file (in this case, it's `MIT`).[^whole-game-use_mit_license]

[^whole-game-use_mit_license]: `use_mit_license()` will automatically include the `LICENSE.md` file in the root folder (and includes the necessary pattern in the `.Rbuildignore` to exclude it from the package builds).

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding 'MIT + file LICENSE' to License
✔ Writing 'LICENSE'
✔ Writing 'LICENSE.md'
✔ Adding '^LICENSE\\.md$' to '.Rbuildignore'
```

## Document {#sec-use-roxygen2}

After writing `roxygen2` documentation for the data, modules, and standalone app function, calling `devtools::document()()` generates the `.Rd` files and `NAMESPACE`.[^whole-game-roxygen2-skeleton] 

[^whole-game-roxygen2-skeleton]: You can include an Roxygen skeleton in the IDE by clicking on **Code** > **Insert Roxygen Skeleton**, or using the keyboard shortcut: [<kbd>Option/⌥</kbd> + <kbd>Shift⇧</kbd> + <kbd>Ctrl/Cmd</kbd> + <kbd>R</kbd>]{style="font-weight: bold; font-style: italic;"}

```{r}
#| eval: false
#| code-fold: false
devtools::document()
```

The output from `document()` tells us what files have been created (and if there were any errors in them).[^whole-game-document]

[^whole-game-document]: The files created by `document()` rely on the `roxygen2` package (and should not be edited manually).

```{verbatim}
#| eval: false
#| code-fold: false
ℹ Updating monthAppPkg documentation
ℹ Loading monthAppPkg
Writing NAMESPACE
Writing NAMESPACE
Writing birthstoneUI.Rd
Writing birthstoneServer.Rd
Writing monthApp.Rd
Writing monthFeedbackUI.Rd
Writing monthFeedbackServer.Rd
```

### Namespace {#sec-use-namespace}

The `NAMESPACE` file contains the imported and exported functions from `monthAppPkg`:[^whole-game-namespacing]

[^whole-game-namespacing]: We're importing the everything from `shiny` and only `load_all` from `pkgload`): 

```{verbatim}
#| eval: false
#| code-fold: false
# Generated by roxygen2: do not edit by hand

export(birthstoneServer)
export(birthstoneUI)
export(monthApp)
export(monthFeedbackServer)
export(monthFeedbackUI)
import(shiny)
importFrom(pkgload,load_all)

```


## RStudio project options ![](images/rproj_icon.png){height=30} {#sec-use-rstudio-project-options}

If you're developing in RStudio, we need to update our `.Rproj` file to enable the **Build** pane and keyboard shortcuts:

```{r}
#| eval: false
#| code-fold: false
file.edit("monthAppPkg.Rproj")
```

If your app-package was initially built as an RStudio project (i.e., not as a package), the following fields should be included at the bottom of `monthAppPkg.Rproj`:  

```{verbatim}
#| eval: false
#| code-fold: false
BuildType: Package
PackageUseDevtools: Yes
PackageInstallArgs: --no-multiarch --with-keep.source
PackageRoxygenize: rd,collate,namespace
```

These options are also available under **Tools** > **Project Options ...** > **Build Tools**

## Git {#sec-use-git}

The `use_git()` step is performed much earlier in [R Packages, 2ed](https://r-pkgs.org/whole-game.html#use_git), but I've saved it for this step because using Git will prompt the IDE to re-initialize and display the **Git** pane (and it will also read our new settings in the `.Rproj` file).

```{verbatim}
#| eval: false
#| code-fold: false
✔ Setting active project to '/projects/apps/monthAppPkg'
✔ Initialising Git repo
✔ Adding '.Rproj.user', '.Rhistory', '.Rdata', '.httr-oauth', '.DS_Store', '.quarto' to '.gitignore'
There are 12 uncommitted files:
* '.gitignore'
* '.Rbuildignore'
* 'app.R'
* 'data/'
* 'DESCRIPTION'
* 'LICENSE'
* 'LICENSE.md'
* 'man/'
* 'monthAppPkg.Rproj'
* 'NAMESPACE'
* ...
Is it ok to commit them?

1: Absolutely not
2: Not now
3: Absolutely
```

Agree to commit these files:

```{verbatim}
#| eval: false
#| code-fold: false
Selection: 3
✔ Adding files
✔ Making a commit with message 'Initial commit'
• A restart of RStudio is required to activate the Git pane
Restart now?

1: Not now
2: Negative
3: Absolutely
```

Restarting RStudio will activate the **Git** and **Build** panes: 

![Git Pane](images/whole_game_git_pane.png){width=100% fig-align='center'}

![Build Pane](images/whole_game_build_pane.png){width=100% fig-align='center'}

This will also activate the `devtools` keyboard shortcuts: 

## Keyboard shortcuts {#sec-use-keyboard-shortcuts}

The `devtools` keyboard shortcuts are available in RStudio and Positron.

::: {layout="[50, 50], [50, 50]]"}

#### `load_all()` {.unnumbered}

[<kbd>Shift</kbd> + <kbd>Ctrl/Cmd</kbd> + <kbd>L</kbd>]{style="font-weight: bold; font-style: italic;"}

#### `document()` {.unnumbered}

[<kbd>Shift</kbd> + <kbd>Ctrl/Cmd</kbd> + <kbd>D</kbd>]{style="font-weight: bold; font-style: italic;"}

#### `install()` {.unnumbered}

[<kbd>Shift</kbd> + <kbd>Ctrl/Cmd</kbd> + <kbd>B</kbd>]{style="font-weight: bold; font-style: italic;"}

#### `test()` {.unnumbered}

[<kbd>Shift</kbd> + <kbd>Ctrl/Cmd</kbd> + <kbd>T</kbd>]{style="font-weight: bold; font-style: italic;"}

:::

## Install {#sec-use-pkg-install}

Installing `monthAppPkg` with `devtools::install()` produces see the following output in the **Build** pane:

```{verbatim}
#| eval: false
#| code-fold: false
==> devtools::document(roclets = c('rd', 'collate', 'namespace'))

ℹ Updating monthAppPkg documentation
ℹ Loading monthAppPkg
Documentation completed

==> R CMD INSTALL --preclean --no-multiarch --with-keep.source monthAppPkg

* installing to library ‘/path/to/Library/R/x86_64/4.2/library’
* installing *source* package ‘monthAppPkg’ ...
** using staged installation
** R
** data
*** moving datasets to lazyload DB
** byte-compile and prepare package for lazy loading
** help
*** installing help indices
** building package indices
** testing if installed package can be loaded from temporary location
** testing if installed package can be loaded from final location
** testing if installed package keeps a record of temporary installation path
* DONE (monthAppPkg)
```

Back in the **Console**, RStudio will restart and call `library(monthAppPkg)`:

```{verbatim}
#| eval: false
#| code-fold: false
Restarting R session...

> library(monthAppPkg)
```

We can now launch the app using `monthApp()`

```{r}
#| eval: false
#| code-fold: false
monthApp()
```

![Our `monthApp()` application](images/whole_game_monthApp.png)

```{r}
#| label: git_box_monthAppPkg_main
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  fig_pw = '75%', 
  branch = "01_whole-app-game", 
  repo = 'sap')
```

## Additional files {#sec-use-additional-files}

The following sections cover additional files you should include in your ap-package (but are not required). 

### README {#sec-use-readme-rmd}

A `README.md` file is the initial point of contact for users and/or contributors looking for information about your app-package. `use_readme_rmd()` will create a `README.Rmd` (i.e., the file you'll edit), which serves as the source document for your `README.md`.

```{r}
#| eval: false
#| code-fold: false
usethis::use_readme_rmd()
```

The `README.Rmd` pattern is automatically added to the `.Rbuildignore`, and includes a Git 'pre-commit' hook:[^whole-game-use_readme_rmd]

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding '^README\\.Rmd$' to '.Rbuildignore'
✔ Writing '.git/hooks/pre-commit'
```

[^whole-game-use_readme_rmd]: This Git behavior is designed to prevent us from making changes to the `README.Rmd` and forgetting to re-render the `README.md`. If you find this behavior confusing or would like to disable it, run the following commands in the **Terminal**: `rm .git/hooks/pre-commit`


### NEWS.md {#sec-use-news-md}

A `NEWS.md` is helpful for logging updates to your app-package and tracking release information.

```{r}
#| eval: false
#| code-fold: false
usethis::use_news_md()
```

`use_news_md()` will also prompt me to add and commit this file to the Git repository:

```{verbatim}
#| eval: false
#| code-fold: false
There is 1 uncommitted file:
* 'NEWS.md'
Is it ok to commit it?

1: Negative
2: Yeah
3: Absolutely not

Selection: 2
✔ Adding files
✔ Making a commit with message 'Add NEWS.md'
```

The contents of the `NEWS.md` are below:[^whole-game-use_news_md]

``` Markdown
# monthAppPkg (development version)

* Initial CRAN submission.
```

[^whole-game-use_news_md]: The `Initial CRAN submission` bullet doesn't apply to `monthAppPkg`, so I'll remove it and re-commit/push the `NEWS.md` file.

### Vignettes {#sec-use-vignette}

Vignettes can be used to store detailed tutorials, explanations of core concepts, use-cases, FAQs and troubleshooting, integration with other packages, etc.

```{r}
#| eval: false
#| code-fold: false
use_vignette("monthAppPkg")
```

The first time we call `use_vignette()` will prompt usethis to add the following fields in the `DESCRIPTION`: 

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding 'knitr' to Suggests field in DESCRIPTION
✔ Adding 'rmarkdown' to Suggests field in DESCRIPTION
✔ Adding 'knitr' to VignetteBuilder
```

The following files are also included in the `.gitignore`:

```{verbatim}
#| eval: false
#| code-fold: false
✔ Adding 'inst/doc' to '.gitignore'
✔ Creating 'vignettes/'
✔ Adding '*.html', '*.R' to 'vignettes/.gitignore'
```

## Recap

In this chapter we've covered the steps used to create a package containing a Shiny application. 

```{r}
#| label: git_contrib_box
#| echo: false
#| results: asis
#| eval: true
git_contrib_box()
```