Chapter 8 Setting up for success with {golem} (#settingupsuccess)

Before starting to prototype and build anything, initialize a {golem} (Fay 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.

8.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:

# Creating a golem project from the command line
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:

Error : [ENOENT] Failed to remove '/home/runner/work/engineering-shiny-book/engineering-shiny-book/golex/inst/app/www/plop.js': no such file or directory
# This is what a default {golem} project looks like
fs::dir_tree("golex")
golex
├── DESCRIPTION
├── NAMESPACE
├── R
│   ├── app_config.R
│   ├── app_server.R
│   ├── app_ui.R
│   ├── mod_my_first_module.R
│   └── run_app.R
├── dev
│   ├── 01_start.R
│   ├── 02_dev.R
│   ├── 03_deploy.R
│   └── run_dev.R
├── inst
│   ├── app
│   │   └── www
│   │       ├── custom.css
│   │       ├── favicon.ico
│   │       ├── first_handler.js
│   │       └── script.js
│   └── golem-config.yml
└── man
    └── run_app.Rd

If you already have some experience with R packages, most of these files will appear very familiar to you. That’s because a {golem} app IS a package, so it uses the standard R pakage structure (and yes, the good news is that everything you know about R packages will work in a {golem} based application).

8.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

8.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, which will add information to the golem-config.yml file, and set the {here} (Müller 2017) package root sentinel. {here} is an R package designed to handle directory management in R. When used in combination with {golem}, {here} helps ensuring that everything you do in your console is performed relatively to the root directory of your project: the one containing the DESCRIPTION of your application. That way, even if you change the working directory of your R session to a subfolder, you will still be able to create modules and CSS files in the correct folder.

8.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" )  
# Add a README, Code of Conduct, lifecycle badge and NEWS.md file to your application
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()

8.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.

# These files will create R/golem_utils_ui.R and R/golem_utils_server.R
golem::use_utils_ui()
golem::use_utils_server()

In this file, you will for example find list_to_li(), which is a function to turn an R list into an HTML list or with_red_star(), a function to add a small red star after an UI input, useful for communicating that an input is mandatory.

8.2.5 Changing the favicon

Favicons are the small icon located on the tab of your browser: in the default application, this favicon is the {golem} hex.

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.

8.3 Setting infrastructure for prototyping

8.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.

# Creating a module skeleton
golem::add_module(name = "my_first_module") 
✔ File already exists.
● 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 Functions
#'
#' @noRd 
mod_my_first_module_server <- function(id){
  moduleServer( id, 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
# 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.

8.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 specific file where they can write the JavaScript and CSS code.

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.

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

Fay, Colin, Vincent Guyader, 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.


ThinkR Website