{golem} from CRAN:Note before using {golem}:
A {golem} app is contained inside a package, so knowing how to build a package is highly recommended. On the plus side, everything you know about package development can be reused in {golem}.
A {golem} app works better if you are working with shiny modules, so knowing how modules work is recommended, but not mandatory.
In the rest of the Vignettes, we’ll assume you’re working in RStudio.
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:
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.
DESCRIPTION & NAMESPACE: Package meta-data.
R/app_config.R: Used to read inside {golem} config file located at inst/golem-config.yml.
R/app_server.R, R/app_ui.R: Top level UI and server elements.
R/run_app.R: a function to configure and launch the application.
dev/: Scripts that will be used along the process of developing your app. You don’t need to fill all the script before starting: use them as a notebook for keeping track of what you’re doing all along the project life.
inst/app/www: Where you will add external dependencies in www (images, css, etc), notably added with the golem functions used to create external resources.
man: Package documentation, to be generated by R & {roxygen2}.
dev/01_start.ROnce 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.
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.
About the DESCRIPTION file.
{golem} optionsPlease 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()
If you want to use the MIT license, README, code of conduct, lifecycle badge, a news file, etc.
See {usethis} for more info about these functions.
This will add “shiny”, “DT”, “attempt”, “glue”, “htmltools”, and “golem” as a dependency to your package.
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
.pngextension, otherwise it is not going to work. + Utils
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.
To run the app, go to the dev/run_dev.R file, and launch the all thing.
You’re now set! You’ve successfully initiated the project and can go to dev/02_dev.R.
{golem}Now that you’re all set with your project init, time to move to development!
App development should happen through the dev/02_dev.R file, which contains common commands for developing.
To run the app, go to the dev/run_dev.R file, and run the all thing.
dev/02_dev.RTo be called each time you need a new package as a dependency:
About package dependencies.
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.
The new file will contain:
At the end of the file, you will find a piece of code that has to be copied and pasted inside your UI and server functions.
These two function create R/fct_helpers.R and R/utils_helpers.R, two file you can use to add business logic functions.
These functions create external dependencies (JavaScript and CSS). add_js_file() creates a simple JavaScript file, while add_js_handler() adds a file with a skeleton for shiny custom handlers.
Note: While the general philosophy of {golem} is being based on the idea that you’re building a package, these functions can be used outside of a {golem} project.
Note that you can also download external CSS and JavaScript files with:
The above has the effect of downloading the file at the specified url and giving it a provided name. If the intent is to use a CDN hosted CSS/JS file then manually add the tag - tags$script(src = "source_of_ur_css/js") in the function golem_add_external_resources in file app-ui.R. The tag can be added inside the tags$head(...) if the intent is to load the js/css file in the <head> of the document or outside it if it is intended in the <body>.
You can add any external resource into inst/app/www.
JavaScript and CSS are automatically linked in the golem_add_external_resources() function. If you add other resources (example images), you can link them in the app with the www prefix:
You can also list here the use of other packages, for example useShinyalert() from the {shinyalert} package.
{golem} dev functionsThere’s a series of tools to make your app behave differently whether it’s in dev or prod mode. Notably, the app_prod() and app_dev() function tests for options( "golem.app.prod") (or return TRUE if this option doesn’t exist).
Setting this options at the beginning of your dev process allows to make your app behave in a specific way when you are in dev mode. For example, printing message to the console with cat_dev().
You can then make any function being “dev-dependent” with the make_dev() function:
run_app() functionWhen launching the app, you might have noticed that the dev/run_dev.R function calls run_app(), which has the following structure:
This function might looks a little bit weird, but there’s a long story behind it, and you can read more about it there.
But long story short, this combination of with_golem_options & golem_opts = list(...) allows you to pass argument to the function to be used inside the application, from UI or from server side, which you can get with get_golem_options().
The idea is to provide more flexibility for deployment on each platform you want to run your app on.
{golem}The dev/03_deploy.R file contains function for deploying on various platforms.