Getting Started with {golem}

Colin Fay

2022-07-13

Installing {golem}

install.packages("golem")

The development version of {golem} can be installed from GitHub using the {remotes} package:

remotes::install_github("Thinkr-open/golem")

Getting started

Note before using {golem}:

In the rest of the Vignettes, we’ll assume you’re working in RStudio.

Create a package

Once the package is installed, you can got to File > New Project… in RStudio, and choose “Package for Shiny App Using golem” input.

If you want to do it through command line, you can use:

golem::create_golem(path = "path/to/package")

This command allows you to create “illegally-named” package (for example, 1234) by passing the check_name argument to FALSE. Note that this is not recommended and should only be done if you know what you are doing.

Once you’ve got that, a new RStudio project will be launched. Here is the structure of this project:

#> ├── DESCRIPTION 
#> ├── NAMESPACE 
#> ├── R 
#> │   ├── app_config.R 
#> │   ├── app_server.R 
#> │   ├── app_ui.R 
#> │   └── run_app.R 
#> ├── dev 
#> │   ├── 01_start.R 
#> │   ├── 02_dev.R 
#> │   ├── 03_deploy.R 
#> │   └── run_dev.R 
#> ├── inst 
#> │   ├── app 
#> │   │   └── www 
#> │   │       └── favicon.ico 
#> │   └── golem-config.yml 
#> └── man 
#>     └── run_app.Rd

If you’re already familiar with R packages, most of these files will seem very familiar to you. That’s because a {golem} app IS a package.

dev/01_start.R

Once you’ve created your project, the first file that opens is dev/01_start.R. This file contains a series of commands that you’ll have to run once, at the beginning of the project.

Note that you don’t have to fill everything, event thought it’s strongly recommended.

Fill the DESCRIPTION

First, fill the DESCRIPTION by adding information about the package that will contain your app. The first function, fill_desc(), can be used to fill your DESCRIPTION file.

golem::fill_desc(
  pkg_name = "shinyexample", # The Name of the package containing the App
  pkg_title = "PKG_TITLE", # The Title of the package containing the App
  pkg_description = "PKG_DESC.", # The Description of the package containing the App
  author_first_name = "AUTHOR_FIRST", # Your First Name
  author_last_name = "AUTHOR_LAST", # Your Last Name
  author_email = "AUTHOR@MAIL.COM", # Your Email
  repo_url = NULL # The (optional) URL of the GitHub Repo
)

About the DESCRIPTION file.

Add {golem} options

Please DO run this line of code, as it sets a series of global options inside golem-config.yml that will be reused inside {golem}.

golem::set_golem_options()

Set common Files

If you want to use the MIT license, README, code of conduct, lifecycle badge, a news file, etc.

## See ?usethis for more information
usethis::use_mit_license("Golem User") # You can set another license here
usethis::use_readme_rmd(open = FALSE)
usethis::use_code_of_conduct()
usethis::use_lifecycle_badge("Experimental")
usethis::use_news_md(open = FALSE)

See {usethis} for more info about these functions.

Init Tests

Create a template for tests:

golem::use_recommended_tests()

About tests in a package.

Add various tools

# Remove current favicon
golem::remove_favicon()
# Add a new one
golem::use_favicon(path = "path/to/favicon")

Note that you can add an url, and the favicon will be downloaded to the inst/app/www folder.

Note: If you are deploying your app with ShinyProxy, your favicon should have the .png extension, otherwise it is not going to work.

These two functions add a file with various functions that can be used along the process of building your app.

See each file in details for a description of the functions.

golem::use_utils_ui()
golem::use_utils_server()

Try the app

To run the app, launch :

golem::run_dev()

You’re now set! You’ve successfully initiated the project and can go to dev/02_dev.R.

rstudioapi::navigateToFile("dev/02_dev.R")
try(fs::dir_delete(x), silent = TRUE)