packages.qmd

# Packages {#sec-pkgs}

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

```{r}
#| label: co_box_tldr
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "b", 
  look = "default", hsize = "1.10", size = "1.05", 
  header = "![](images/rpkg_icon_no_bkgrnd.png){height=40} TLDR ", 
  fold = TRUE,
  contents = "
  
<br>
  
Functional packages require three things:
  
  1. A `DESCRIPTION` file with the following fields:\n
  \`\`\`bash
  Package
  Version
  License
  Description
  Title
  Author
  Maintainer
  \`\`\`
  
  2. An `Rproj` file with the following fields:\n
  \`\`\`bash
  BuildType: Package
  PackageUseDevtools: Yes
  PackageInstallArgs: --no-multiarch --with-keep.source
  \`\`\`
  
&emsp; Access these settings via **Tools** > **Project Options** > **Build Tools**
  
  3. `devtools` installed\n
  \`\`\`r
  install.packages('devtools')
  library(devtools)
  \`\`\`
  "
)
```

---

::: {layout="[85, 15]" layout-valign="top"}

This chapter covers the necessary ingredients of R packages. We'll start by exploring the differences between Shiny projects, R packages, and Shiny app-packages. Then, we'll dive into the requirements for 1) creating new Shiny app-packages from scratch, and 2) converting Shiny app projects into app-packages.

![](images/rpkg_icon_no_bkgrnd.png){fig-align="right" width='100%'}

:::


```{r}
#| label: shinypak_apps
#| echo: false
#| results: asis
#| eval: true
shinypak_apps(regex = "^03", branch = "03.1_description")
```


Before we start, we should establish some operational definitions of what is meant by the terms ‘project,’ ‘package,’ and ‘app-package.’


-  **Shiny Projects** ![](images/00_index_shiny.png){height=30}

    -   I consider a Shiny app project to be a directory containing a Shiny application (in an `app.R` file or `ui.R`/`server.R` files)[^shiny-rproj]   

-  **R Packages** ![](images/rpkg_small_v2.png){height=30} 

    -   I'll use the term **R package** to describe a directory with the necessary dependency management (`NAMESPACE`), metadata files (`DESCRIPTION`), and R code to be successfully installed and loaded into an R session[^pkg-rproj]

-  **Shiny app-packages** ![](images/shinyap_small_v2.png){height=30} 
    -   A **Shiny app-package**--which you have probably already guessed--is an R package containing a Shiny application. 

:::{.column-margin}

I'll differentiate Shiny app projects, R packages, and Shiny app-packages using icons

:::

[^shiny-rproj]: If you're developing in RStudio ![](images/rstudio-icon.png){height=20}, your Shiny project might also include a Posit workbench project file (`.Rproj`).

[^pkg-rproj]: If you're working in RStudio ![](images/rstudio-icon.png){height=20}, your R package will also likely include a project file (`.Rproj`).

There are multiple reasons for deciding to develop a Shiny app-package, but if you're reading this book, you've likely found yourself in one of two circumstances:

1. You want to develop a new app, but want it structured as an R package ![](images/rpkg_small_v2.png){height=30}.  

2. You've already developed a Shiny project ![](images/00_index_shiny.png){height=30}, but now you need to convert it into an R package![](images/rpkg_small_v2.png){height=30}

The previous chapters covered a few practices to adopt during development that improve the extensibility of your app and will make it easier to convert into a Shiny app-package.[^pkgs-shiny-development]

[^pkgs-shiny-development]: Shiny app project features are covered in @sec-shiny-folders and @sec-shiny-files of the previous chapter.


## R packages ![](images/rpkg_small_v2.png){height=30} {#sec-packages-r-pkgs}

R packages can be easily shared, reused, and reproduced because they all have a similar structure, and each folder and file plays an essential role in extending R’s capabilities. Below is a folder tree with some of the typical files and folders found in R packages:[^pkgs-folder-trees]

```{bash}
#| eval: false
#| code-fold: false
#| echo: true
<R package>/
    ├── DESCRIPTION # <1>
    ├── <R package>.Rproj # <2>
    ├── LICENSE # <3>
    ├── LICENSE.md # <3>
    ├── NAMESPACE # <4>
    ├── NEWS.md # <5>
    ├── README.Rmd # <6>
    ├── README.md # <6>
    ├── renv.lock # <7>
    ├── R/ # <8>
    ├── man/ # <9>
    ├── tests/ # <10>
    ├── data/  # <11>
    ├── data-raw/  # <12>
    ├── vignettes/  # <13>
    ├── inst/  # <14>
    └── renv/ # <15>
  
```
1. Metadata file with the package's purpose, dependencies, authors, and other essential information.  
2. RStudio project file for managing and organizing the package's development environment. 
3. Specifies the terms under which the package can be used, modified, and distributed. 
4. Defines the functions and datasets exported by the package and the imports from other packages.  
5. Contains a changelog detailing updates and changes made across package versions. 
6. Provides an overview of the package, usage examples, and installation instructions (typically for display on GitHub).  
7. Contains he exact package versions and dependencies for a reproducible development environment. 
8. All the R scripts with the package's functions and main code.
9. Documentation files for functions and datasets in `.Rd` format, generated using tools like `roxygen2`.  
10. Stores unit tests to validate the functionality of the package, often using frameworks like `testthat`. 
11. Includes preprocessed datasets provided with the package, saved in `.RData` or `.rda` format.
12. Raw data and scripts for processing it into the format stored in the `data/` folder.
13. Long-form documentation and tutorials, written in RMarkdown, explaining package usage in depth.  
14. directory for additional files installed with the package, such as documentation, examples, or datasets.  
15. Manages the package's dependencies in an isolated environment, ensuring reproducibility. 

[^pkgs-folder-trees]: Fortunately, Shiny app-packages don't require *all* the files and folders displayed in the folder tree to gain the functionality and benefits of an R package. 

The sections below cover the minimum requirements for an R package, so you can handle both creating new Shiny app-packages and converting existing Shiny projects into Shiny app-packages.

### Essential ingredients {#sec-packages-essential-ingredients}

If you've done some research on R packages, you've probably encountered one (or both) of the following statements, 

> *'RStudio and `devtools` consider any directory containing `DESCRIPTION` to be a package'* - [R Packages, 2ed (Chapter 9, `DESCRIPTION`)](https://r-pkgs.org/description.html#the-description-file)
> 
> *'all a project needs to be a package is a directory of `R/` files and a `DESCRIPTION` file.'* - [Mastering Shiny (Chapter 20, Packages)](https://mastering-Shiny.org/scaling-packaging.html#summary-18)


Below is the current `sap` app folder: 

```{bash}
#| eval: false
#| code-fold: false
sap/
├── DESCRIPTION # <1>
├── sap.Rproj 
├── R/ # <2>
│   ├── mod_scatter_display.R
│   ├── mod_var_input.R
│   └── utils.R
├── README.md
├── app.R
├── movies.RData
└── www/
    └── shiny.png

4 directories, 9 files
```
1. `DESCRIPTION` file  
2. `R/` folder with `.R` files  

We can see sap has: 

- [x] a `DESCRIPTION` file 

- [x] an `R/` directory

So, is `sap` a functioning R package? 

#### Can we load it with [`devtools`]{style="font-size: 1.05em; font-weight: bold;"}?

Package development kicks off with the `load_all()` function from `devtools`, which is similar to calling `library()` (we'll cover this function extensively in the [Development](development.qmd) chapter). 

However, when we attempt to load the code in the `R/` folder with `load_all()`, we see the following error:

```{r}
#| eval: false 
#| code-fold: false
install.packages("devtools")
library(devtools)
devtools::load_all()
```

![`devtools` is looking for the **`Package` field** in our `DESCRIPTION` file](images/pkgs_load_all_error.png){width="100%" fig-align="center"}

#### Does it have a [`DESCRIPTION`]{style="font-size: 1.05em; font-weight: bold;"}?

```{r}
#| label: git_box_3.1_description
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  fig_pw = '75%', 
  branch = "03.1_description", 
  repo = 'sap')
```

The official R documentation[^pkgs-9] lists the following required fields for the `DESCRIPTION` in R packages:

[^pkgs-9]: The mandatory fields are covered in [Writing R Extensions, 'The DESCRIPTION file'](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file)

> *The ‘Package’, ‘Version’, ‘License’, ‘Description’, ‘Title’, ‘Author’, and ‘Maintainer’ fields are mandatory.*

Below is an example `DESCRIPTION` file for our new `sap` package with the mandatory fields:[^pkgs-10]

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

```{bash}
#| eval: false
#| code-fold: false
Package: sap
Title: Shiny App-Packages
Version: 0.0.0.9000
Author: John Smith [aut, cre]
Maintainer: John Smith <John.Smith@email.io>
Description: An R package with a collection of Shiny applications.
License: GPL-3

```

::: {.callout-tip title="`Author` and `Maintainer` fields" collapse='true'}

Note that the `Author` and `Maintainer` fields require additional information beyond first and last name (i.e., `John Smith`). These can be created with the `utils::person()` function:

```{r}
#| collapse: true
#| code-fold: false 
#| code-summary: 'show/hide person() output'
# Author
utils::person(
  given = "John", 
  family = "Smith", 
  role = c("aut", "cre"))
# Maintainer
utils::person(
  given = "John", 
  family = "Smith", 
  email = "John.Smith@email.io")
```

:::



### RStudio's Build pane ![](images/rstudio-icon.png){height=20} {#sec-packages-rstudio-build-pane}

If you're using RStudio, then functioning R packages also have access to the **Build** pane, which allows us to quickly load, install, and test code. When we open `sap`, the **Build** pane is not displayed in the IDE:


![The **Build** pane is normally between **Connections** and **Git**](images/pkgs_no_build_pane.png){width="100%" fig-align="center"}

After adding the seven mandatory fields to the `DESCRIPTION` file, `devtools::load_all()` runs without the previous error, but the IDE still doesn't display the **Build** pane: 

![Where is the **Build** pane?](images/pkgs_desc_no_build_pane.png){height="100%" width="100%" fig-align="center"}


#### RStudio projects ![](images/rproj_icon.png){height=20} 

`.Rproj` files are plain text files with various configurations for the RStudio IDE. We were able to run `devtools::load_all()` above *without* the presence of the **Build** pane because RStudio displays the **Build** pane after reading the fields in the `.Rproj` file.  

The quickest way to access the fields in the `.Rproj` file is under **Tools** > **Project Options...**.

#### Project options 

Selecting **Tools** > **Project Options...** will provide us access to the project-level options. For example, fields 2 - 4 are available under **General**, 5 - 8 affect the **Code** options, and the final two fields deal with **Sweave**. 


![Field settings from `sap.Rproj` file](images/pkgs_proj_options.png){width="100%" fig-align="center"}


The default settings were created when we selected the Shiny app project from the **New Project Wizard** in the last chapter.

#### Build tools

I've placed the `.Rproj` file from `sap` with the example `.Rproj` file from [R Packages, (2ed)](https://r-pkgs.org/) side-by-side so you can compare them below:[^pkgs-11]

[^pkgs-11]: `.Rproj` files are covered in the [What makes an RStudio Project? section of R Packages (2 ed)](https://r-pkgs.org/workflow101.html#what-makes-an-rstudio-projec)

::: {#fig-pkgs_rproj_fields}
![`.Rproj` files](images/pkgs_rproj_fields.png){#fig-pkgs_rproj_fields  width="100%" fig-align="center"}

Comparison of `sap.Rproj` file and `.Rproj` file in [R Packages, 2ed](https://r-pkgs.org/workflow101.html#what-makes-an-rstudio-project)
:::

I've circled the fields in the `.Rproj` file that illustrate it's configured to work with an R package. Note that in `sap`, the **Project build tools** are initially set to (**None**) under **Build Tools**:

::: {#fig-pkgs_proj_opts_build_tools}
![`sap.Rproj` build tools](images/pkgs_proj_opts_build_tools.png){#fig-pkgs_proj_opts_build_tools height="100%" width="100%" fig-align="center"}

Build tool settings in `sap.Rproj` file
:::

Changing the **Project build tools** option to **Package** will set the default **Build Tools** options:[^pkgs-12]

[^pkgs-12]: The initial **Build Tools** settings (i.e., **(None)**) should help explain the absence of any R package development fields in the `sap.Rproj` when we compared it to the version in [R Packages, 2ed](https://r-pkgs.org/workflow101.html#what-makes-an-rstudio-project) (i.e., `BuildType`, `PackageUseDevtools`, `PackageInstallArgs`, and `PackageRoxygenize`). 

::: {#fig-pkgs_proj_opts_build_tools_pkg}
![Default package build tools](images/pkgs_proj_opts_build_tools_pkg.png){#fig-pkgs_proj_opts_build_tools_pkg height="100%" width="100%" fig-align="center"}

Default build tool settings
:::

The links between the **Build Tools** options and fields in `sap.Rproj` are in the figure below:

::: {#fig-pkgs_rproj_connect_build_tools}
![`sap.Rproj` build tool fields](images/pkgs_rproj_connect_build_tools.png){#fig-pkgs_rproj_connect_build_tools width="100%" fig-align="center"}

Default build tool settings in `sap.Rproj` file
:::

-   `BuildType: Package` tells the IDE `sap` is an R package and triggers the **Build** pane.

-   `PackageUseDevtools: Yes` links the options in the **Build** pane to the [`devtools` package](https://devtools.r-lib.org/).

-   The `PackageInstallArgs` are complicated, but I've included some information about them in the callout block below (and you can read more in the [official R documentation](https://cran.r-project.org/manuals.html))


-   The fourth option (`PackageRoxygenize`) is available under **Generate documentation with Roxygen** > **Use roxygen to generate**:
    -   These options affect the documentation in an R package. To match the example from [R Packages, 2ed](https://r-pkgs.org/workflow101.html#what-makes-an-rstudio-project) above, make sure **Rd files**, **Collate field**, and **NAMESPACE file** are selected and click **OK**.


::: {#fig-pkgs_roxygenize_on_build}
![`PackageRoxygenize` in `.Rproj` file](images/pkgs_roxygenize_on_build.png){#fig-pkgs_roxygenize_on_build width="100%" fig-align="center"}

`roxygen2` build settings
:::

After clicking **OK**, the IDE will automatically reboot, and the additional fields will be added to the bottom of the `sap.Rproj`:

```{r}
#| label: git_box_03.2_rproj
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  branch = "03.2_rproj", 
  repo = 'sap')
```

```{bash}
#| eval: false
#| code-fold: false
Version: 1.0

RestoreWorkspace: Default
SaveWorkspace: Default
AlwaysSaveHistory: Default

EnableCodeIndexing: Yes
UseSpacesForTab: Yes
NumSpacesForTab: 2
Encoding: UTF-8

RnwWeave: Sweave
LaTeX: XeLaTeX

BuildType: Package
PackageUseDevtools: Yes
PackageInstallArgs: --no-multiarch --with-keep.source
PackageRoxygenize: rd,collate,namespace
                                            
```

```{r}
#| label: co_rproj_package_install_args
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g",
  fold = TRUE,
  look = "default", hsize = "1.10", size = "1.05", 
  header = "What is `--no-multiarch --with-keep.source`?",
  contents = "
  -   `--no-multiarch`: refers to the option for the package installer to only compile the package for the architecture of the current R session. By default, R tries to compile packages for 32-bit and 64-bit architectures if running in a 64-bit R session on Windows. This flag can help avoid problems if a package can only be compiled on one architecture. Read more [here](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#Checking-installed-source-packages).
  
  -   `--with-keep.source`: In R, when a function is created, its body can be stored in two ways: 1) as a parsed but unevaluated expression and 2) as a character string containing the function's source code. By default, only the parsed expression is kept. If `–with-keep.source` is specified, R will also keep the source code as a character string, which can be helpful for debugging and tools that analyze or modify source code. Read more [here](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Tidying-R-code).
    "
)
```

When the new session starts, the new project-level options activate the **Build** pane in the IDE, and I can check the R package functionality by loading the code with **Build** > **Load All**


![Identical to running `devtools::load_all()`](images/pkgs_build_menu.png){width="100%" fig-align="center"}

### Positron's workspaces ![](images/positron.png){height=20} {#sec-packages-positron-workspaces}

Positron doesn't recognize RStudio's project files (`.Rproj`) or their build tools configuration. Instead, Positron organizes files and paths around workspaces.[^positron-conf-2024] 

A workspace is any folder that contains your project's files. You can open an existing folder or create a new one from Positron's welcome pane:

![](images/pkgs_positron_welcome.png){width="100%" fig-align="center"}

#### Positron projects

The **Welcome** pane also offers an option for creating a **New Project**, but this shouldn't be confused with creating an RStudio project.

If we follow the steps for a new project by specifying the type, name, and location: 


:::{layout="[50,50]" layout-valign="top"}

![](images/pkgs_positron_project_type.png){width="100%" fig-align="center"}


![](images/pkgs_positron_project_name_location.png){width="100%" fig-align="center"}

:::

We see this opens a folder in the IDE *without* an `.Rproj` file:

:::{layout="[50,50]" layout-valign="top"}

![](images/pkgs_positron_project_config.png){width="100%" fig-align="center"}

![](images/pkgs_positron_project_open.png){width="100%" fig-align="center"}
:::

If you're building your Shiny app from scratch, this is still a great way to get started because it makes it easy to adopt best practices (i.e., using Git and `renv`).

#### Build tools

In Positron, all of the package development tools from `devtools` are available, but they are executed and handled a little differently by the IDE. We'll cover these differences more in the [Development](development.qmd), [Degbug](debug.qmd), and [Tests](tests.qmd) chapters. 


[^positron-conf-2024]: Learn more about this in [Jenny Bryan's discussion](https://youtu.be/8uRcB34Hhsw?si=jqdj-TTMak3nGTnL&t=3169) in the [Introducing Positron, a new data science IDE](https://www.youtube.com/watch?v=8uRcB34Hhsw) presentation at `posit::conf(2024)`.

### R packages recap

In summary, to turn a Shiny Project ![](images/00_index_shiny.png){height=30} into a 'functioning' R package![](images/rpkg_small_v2.png){height=30}  that can be installed and loaded into an R session we need: 

1.   A `DESCRIPTION` file containing the seven mandatory fields (`Package`, `Version`, `License`, `Description`, `Title`, `Author`, and `Maintainer`), making running the necessary `devtools` functions possible.[^desc-fields-mandatory]

[^desc-fields-mandatory]: Read more about the [mandatory fields](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file) `DESCRIPTION` fields.

2.   If we're using RStudio, the `.Rproj` file must contain the three package configuration fields[^pkg-config-fields], which makes the **Build** pane accessible and functional.

[^pkg-config-fields]: The `.Rproj` package configuration fields are `BuildType: Package`, `PackageUseDevtools: Yes`, and `PackageInstallArgs: --no-multiarch --with-keep.source`.


## App-packages ![](images/shinyap_small_v2.png){height=30} {#sec-packages-app-pkgs}

Shiny app-packages ![](images/shinyap_small_v2.png){height=30} have all of the functionality of a standard R Package ![](images/rpkg_small_v2.png){height=30} but also contain the files and folders required to successfully develop, run, and deploy a Shiny app ![](images/00_index_shiny.png){height=30}. The Posit documentation lists the following way(s) to create R packages:[^pkgs-15a] 

> 1. Call `usethis::create_package()`.
> 
> 2. In Posit Workbench, do **File** > **New Project** > **New Directory** > **R Package**. This ultimately calls `usethis::create_package()`, so really there’s just one way.
> 

[^pkgs-15a]: This information comes from the [Writing R Packages](https://docs.posit.co/ide/user/ide/guide/pkg-devel/writing-packages.html) documentation for Posit Workbench.

```{r}
#| label: git_box_03.3_create-package
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  fig_pw = '75%', 
  branch = "03.3_create-package", 
  repo = 'sap')
```

`create_package()` is a great option if you're looking for a way to quickly create or convert your Shiny project into a Shiny app-package. In the following sections I'll cover some suggestions for using `create_package()`.[^pkgs-16]

[^pkgs-16]: `usethis::create_package()` is covered in the ['Fundamental development workflows' chapter of R Packages, 2ed](https://r-pkgs.org/workflow101.html)

### New app-packages {#sec-create-new-app-packages}

If you haven't written any code and want to create a new Shiny app-package, [`create_package()`](https://usethis.r-lib.org/reference/create_package.html) is the quickest way to get started.

First, install `devtools`:

```{r}
#| eval: false 
#| code-fold: false
install.packages("devtools")
library(devtools)
```

`devtools` automatically loads `usethis`

```{verbatim}
#| eval: false 
#| code-fold: false
Loading required package: usethis
```

Assuming your current working directory is where you want your new Shiny app-package, call `usethis::create_package()` with the `path` argument set to `getwd()`

```{r}
#| eval: false 
#| code-fold: false
usethis::create_package(path = getwd())
```

This call launches a series of actions:

-   First, the active project is set to whatever was given to the `path` argument. 

    ```{verbatim}
    #| eval: false 
    #| code-fold: false
    ✔ Setting active project to 'path/to/newApp'
    ```
    
-   The `R/` folder and `DESCRIPTION/` file are created:

    ```{verbatim}
    #| eval: false 
    #| code-fold: false
    ✔ Creating 'R/'
    ✔ Writing 'DESCRIPTION'
    ```
    
-   The `NAMESPACE` and `.Rproj` files are created:

    ```{verbatim}
    #| eval: false 
    #| code-fold: false
    ✔ Writing 'NAMESPACE'
    ✔ Writing 'newApp.Rproj'
    ```
    
-   The `.Rproj` is added to the `.Rbuildignore` file, the `.Rproj.user` folder is added to the `.gitignore` and `.Rbuildignore` files.
    
    ```{verbatim}
    #| eval: false 
    #| code-fold: false
    ✔ Adding '^newApp\\.Rproj$' to '.Rbuildignore'
    ✔ Adding '.Rproj.user' to '.gitignore'
    ✔ Adding '^\\.Rproj\\.user$' to '.Rbuildignore'
    ```
    
-   A new session is opened from the new `.Rproj` file:

    ```{verbatim}
    #| eval: false 
    #| code-fold: false
    ✔ Opening 'path/to/newApp/' in new RStudio session
    ```

When the new session opens, `newApp` has the following contents:

```{bash}
#| eval: false 
#| code-fold: false
newApp/
  ├── .Rbuildignore
  ├── .Rproj.user/
  ├── .gitignore
  ├── DESCRIPTION
  ├── NAMESPACE
  ├── R/
  └── newApp.Rproj
```

You're now free to develop `newApp`. Store and document any `.R` files in the `R/` folder, edit the `DESCRIPTION` file with details about the application, read through  [R Packages](https://r-pkgs.org/) and [Mastering Shiny](https://mastering-Shiny.org/), and add the Shiny code to complete your Shiny app-package.

### Converting a Shiny project {#sec-convert-shiny-app-packages}

If you already have a Shiny app project that needs to be converted into a Shiny app-package, you can also use `create_package(path = getwd())` in your root folder, but I recommend using the following arguments:

#### [`DESCRIPTION`]{style="font-size: 0.95em"} arguments

-   **`fields`**: these are arguments passed to `usethis::use_description()`. If the `fields` argument is empty, a boilerplate `DESCRIPTION` file is created (similar to [this one](https://r-pkgs.org/description.html#the-description-file)). 

    -   These boilerplate fields in the `DESCRIPTION` work, but I've found some of the fields are unnecessary (i.e., I've never needed `Authors@R:` or `ORCID`) and inevitably require revision, so I'd prefer to handle this during the creation process (and remove the risk of forgetting to change it later).

    -   All fields should be passed in a `list()` as `field = 'value'` pairs. 

    ```{r}
    #| eval: false 
    #| code-fold: false
    usethis::use_description(
        list(Package = 'sap',
             Version = '0.0.0.9000',
             Title = 'Shiny App-Packages',
             Description = 'An R package with a collection of Shiny applications.',
             "Authors@R" = NULL,
             Author = utils::person(
                given = "John", 
                family = "Smith", 
                role = c("aut", "cre")),
              Maintainer = utils::person(
                given = "John", 
                family = "Smith",
                email = "John.Smith@email.io"),
              License = "GPL-3"))
    ```
    
    -   A few fields require specially formatted values (see the `utils::person()` examples below).
    
        ```{r}
        #| eval: true 
        #| code-fold: false
        utils::person("John", "Smith", 
                      email = "John.Smith@email.io", 
                      role = c("aut", "cre"))
        ```

-   Two additional arguments from `use_description()` are passed to `create_package()`:

    -   **`check_name`**: verifies your Shiny app-package name is valid for CRAN, so we can set this to `FALSE` (unless you're planning on submitting to CRAN)

    -   **`roxygen2`**: is `TRUE` by default and adds the fields required to use `roxygen2` (which I won't cover here because we'll cover documentation in-depth in a future chapter). 

```{r}
#| label: co_box_create_package_dot
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "r", fold = TRUE,
  look = "default", hsize = "1.10", size = "1.05", 
  header = "Don't use `\".\"` with `create_package()`",
  contents = "

When converting your existing Shiny app project into a Shiny app-package with `usethis::create_package()`, don't use `'.'` in the `path` argument:
  
\`\`\`r
usethis::create_package('.')
\`\`\`
  
This will return the following warning about creating nested projects, and ask if you want to proceed anyway:
  
`\`\`r
New project 'sap' is nested inside an existing project
'./', which is rarely a good idea. If this is unexpected, 
the here package has a function,
`here::dr_here()` that reveals why './' is regarded as a
project.
  
Do you want to create anyway?

1: Yes
2: No way
3: Not now
`\`\`\


We can avoid this warning altogether by passing `getwd()` to the `path` argument, so I recommend cancelling the project creation:

\`\`\`r
Selection: 2
Error: Cancelling project creation.
\`\`\`

  "
)
```

#### IDE arguments 

-   `rstudio`: adds the necessary **Build Tools** fields in the `.Rproj` file (leave as `TRUE`)

-   `open`: can be set to `FALSE` because we don't need RStudio/Posit Workbench to open in a new session

```{r}
#| eval: false 
#| code-fold: false
usethis::create_package(
  path = getwd(),
  fields = list(Package = 'sap',
         Version = '0.0.0.9000',
         Title = 'Shiny App-Packages',
         Description = 'An R package with a collection of Shiny applications.',
         "Authors@R" = NULL,
         Author = utils::person(
            given = "John", 
            family = "Smith", 
            email = "John.Smith@email.io", 
            role = c("aut", "cre")),
          Maintainer = utils::person(
            given = "John", 
            family = "Smith",
            email = "John.Smith@email.io"),
          License = "GPL-3"),
  roxygen = TRUE,
  check_name = FALSE, 
  rstudio = TRUE,
  open = FALSE)
```

After running `usethis::create_package()` with the arguments above, the IDE will present us with a few prompts to confirm: 

```{verbatim}
#| eval: false 
#| code-fold: false
Overwrite pre-existing file 'DESCRIPTION'?
```

```{verbatim}
#| eval: false 
#| code-fold: false
Overwrite pre-existing file 'sap.Rproj'?
```

The Shiny app-package structure is below:
   
``` sh
├── DESCRIPTION
├── NAMESPACE
├── R
│   ├── mod_scatter_display.R
│   ├── mod_var_input.R
│   └── utils.R
├── README.md
├── app.R
├── movies.RData
├── sap.Rproj
└── www
    └── Shiny.png

3 directories, 10 files
```

The `DESCRIPTION` file (shown below) has a few additional fields (`Encoding`, `Roxygen`, and `RoxygenNote`) we didn't include when we converted `sap` above, but we will cover these in the upcoming chapters. 

``` sh
Package: sap
Title: Shiny App-Packages
Version: 0.0.0.9000
Author: John Smith [aut, cre]
Maintainer: John Smith <John.Smith@email.io>
Description: An R package with a collection of Shiny applications.
License: GPL-3
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.2
```

```{r}
#| label: git_box_launch_03.3_create-package
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  branch = "03.3_create-package")
```

## Recap {.unnumbered}

This chapter has covered the mandatory fields in the `DESCRIPTION` file and the R package configuration fields in `.Rproj`. We also covered creating and converting Shiny app projects using the `usethis::create_package()` function.

```{r}
#| label: co_box_recap
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g", 
  fold = FALSE,
  look = "default", hsize = "1.10", size = "1.05", 
  header = "Recap: Packages!",
  contents = "
  
-   **The `DESCRIPTION` file** ultimately controls whether you have a functional Shiny app-package.
    -   The mandatory fields are `Package`, `Version`, `License`, `Description`, `Title`, `Author`, and `Maintainer`.

-   `usethis::create_package()` can be used to create a new R package and to convert an existing Shiny project into a Shiny app-package.

-   The RStudio IDE reads project (`.Rproj`) files and determines R session settings at the project-level (i.e., working directory, workspace, history, code formatting, etc.)

    -   Package development settings can be accessed via **Project Options** > **Build Tools**.
  
  "
)
```

In the next chapter, I'll cover how you can quickly **Load**, **Document**, and **Install** your package!

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