Chapter 9 Setting up for success with {golem}

Before starting to prototype and build anything, initialize a {golem} (Guyader et al. 2020) project! This will help you start your application on solid ground, and once the project is ready to be filled, you can start prototyping right inside it.

The general workflow for “prototype and build” is the following: the project manager sets up a {golem} project, where the first steps are filled, the general structure (potentially with Shiny module) is set, and then the project is registered to the version control system. Once we have this structure, package and modules combined, we can start prototyping the UI inside the module, work on the CSS and JavaScript elements that might be needed, and prototyping the back-end functionalities inside Rmarkdown files. And then, once this two prototyping sides are finished, we work on the integration of everything inside the reactive context.

In this chapter and in chapter 11, we will be presenting the {golem} package in more depth. {golem} is a framework that standardizes the process of building production-ready Shiny Applications.

9.1 Create a {golem}

Once {golem} is installed and available on your computer, 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")

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

fs::dir_tree("golex")
golex
├── 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 are already familiar with R packages, most of these files will appear very familiar to you. That’s because a {golem} app IS a package.

For more details about these files, please refer to the Understanding {golem} app structure part of this book. In this part, we will go through the dev/01_start.R and dev/02_dev.R scripts.

9.2 Setting things up with dev/01_start.R

Once you have created your project, the first file that opens is dev/01_start.R. This file contains a series of commands to run once, at the start of the project. These are the commands you will be using at

9.2.1 Fill the DESCRIPTION and set options

First, fill the DESCRIPTION file by adding information about the package that will contain your app:

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

Then, call the golem::set_golem_options() function, it will add information to the golem-config.yml file, and notably set the {here} (Müller 2017) package root sentinel.

9.2.2 Set common Files

If you want to use the MIT license, add README, a code of conduct, a lifecycle badge, and NEWS.

# You can set another license here
usethis::use_mit_license( name = "Golem User" )  
usethis::use_readme_rmd( open = FALSE )
usethis::use_code_of_conduct()
usethis::use_lifecycle_badge( "Experimental" )
usethis::use_news_md( open = FALSE )

It’s also where you will be invited to use git:

usethis::use_git()

9.2.4 Add utilitary functions

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()

9.2.5 If you want to change the default favicon

golem::use_favicon( path = "path/to/favicon")

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

9.3 Setting infrastructure for prototyping

9.3.1 Add modules in dev/02_dev.R

The golem::add_module() functions creates a module in the R folder. The file and the modules will be named after the name parameter, by adding mod_ to the R file, and mod_*_ui and mod_*_server to the UI and server functions.

golem::add_module(name = "my_first_module") # Name of the module
✔ File created at R/mod_my_first_module.R
● Go to R/mod_my_first_module.R

The new file will contain:

#' my_first_module UI Function
#'
#' @description A shiny Module.
#'
#' @param id,input,output,session Internal parameters for {shiny}.
#'
#' @noRd 
#'
#' @importFrom shiny NS tagList 
mod_my_first_module_ui <- function(id){
  ns <- NS(id)
  tagList(
 
  )
}
    
#' my_first_module Server Function
#'
#' @noRd 
mod_my_first_module_server <- function(input, output, session){
  ns <- session$ns
 
}
    
## To be copied in the UI
# mod_my_first_module_ui("my_first_module_ui_1")
    
## To be copied in the server
# callModule(mod_my_first_module_server, "my_first_module_ui_1")
 

Note that in order not to make errors when putting these into your app, the end of the file will contain code that has to be copied and pasted inside your UI and server functions.

This is where you will be adding the core of your app. In a first time, these modules will contain prototyped UI for the application, and once the application is ready to be integrated, you will add the core logic here.

9.3.2 Add CSS & JS Files

Adding some infrastructure for JavaScript and CSS file from the very beginning can also formalize the set-up: you are giving the rest of your team a

golem::add_js_file( "script" )

Will generate the following file:

$( document ).ready(function() {
  
});

Here, you will have an infrastructure for launching JavaScript code once the application is ready (this code is standard jQuery format: we will be back to JavaScript at the end of this book).

golem::add_js_handler( "handlers" )

Will generate the following file:

$( document ).ready(function() {
  Shiny.addCustomMessageHandler('fun', function(arg) {
  
  })
});

As you can see, there is already a skeleton for building Shiny JavaScript handlers. More on that structure in the last chapter of the book!

golem::add_css_file( "custom" )

Will create a blank CSS file inside the inst/app/www folder.

Note that if you are building your application with {golem}, these files will be linked automatically to your application.

References

Guyader, Vincent, Colin Fay, Sébastien Rochette, and Cervan Girard. 2020. Golem: A Framework for Robust Shiny Applications. https://github.com/ThinkR-open/golem.

Müller, Kirill. 2017. Here: A Simpler Way to Find Your Files. https://CRAN.R-project.org/package=here.


ThinkR Website