Skip to main content

Engineering Production-Grade Shiny Apps

8 Setting up for Success with {golem}

Before starting to prototype and build anything, initialize a golem (Fay, Guyader, Rochette, et al. 2023) 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 the back-end functionalities inside Rmarkdown files. And then, once these 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 go to File > New Project… in RStudio, and choose “Package for shiny app Using golem” input.

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

# Creating a golem project from the command line
golem::create_golem(path = "path/to/package")

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

# This is what a default {golem} project looks like
# Listing the files from the `golex` project using {fs}
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 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 package 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.

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 2020) package root sentinel. here is an R package designed to handle directory management in R. When used in combination with golem, here helps ensure 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 utility 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 detail 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 a UI input, useful for communicating that an input is mandatory.

8.2.5 Changing the favicon

Favicons are the small icons 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() function 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_1")
    
## To be copied in the server
# mod_my_first_module_server("my_first_module_1")

Note that to avoid making 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. The 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 and JS files

Adding some infrastructure for JavaScript and CSS files 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 as you are building your application with golem, these files will be linked automatically to your application.

ThinkR Website