Preface
Shiny App-Packages attempts to combine and distill Shiny and R package development practices from multiple resources.
Why this book?
Did you read R Packages, 2ed and find it difficult to apply package development practices to your Shiny application?
R Packages, 2ed is the premier resource for learning the best practices when creating functions, writing documentation, managing package namespaces, and many other fundamental aspects of package development. However, R Packages, 2ed primarily focuses on creating conventional R packages, so it doesn’t cover Shiny programming (designing user interfaces, server-side computations, modules, etc.). Moreover, testing and debugging a Shiny application differs from the traditional methods used in R packages.
Did you read Mastering Shiny and want to learn more about package development?
Mastering Shiny is an excellent introduction to the world of Shiny and provides a foundation of best practices for developing applications. R packages are introduced near the end of Mastering Shiny, and this chapter is a great place to start.1 However, to fully understand and appreciate the benefits of developing your Shiny app as an R package, it’s helpful to have an example app-package that includes the full suite of the package development tools (loading, documenting, testing, installing, etc.).2
Other Shiny Resources
Throughout the course of writing this book, the Shiny community has grown and other resources have been published for developing and customizing Shiny applications. Two popular resources are Engineering Production-Grade Shiny Apps and Outstanding User Interfaces with Shiny.
Engineering Production-Grade Shiny Apps introduces the golem
package, which is an ‘opinionated framework for building production-grade Shiny applications’. golem
offers a robust and standardized way to build, maintain, and deploy production-grade Shiny apps. Whether due to the learning curve, number of features, dependencies, or a particular set of deployment constraints, golem
might not be the right fit for your application.3
Outstanding User Interfaces with Shiny ‘addresses a specific gap between the beginner and advanced level’ focusing on customizing your Shiny application with HTML, CSS and JavaScript. It introduces charpente
, which streamlines the creation of Shiny development by quickly creating an R package, importing external web dependencies for JavaScript and CSS, initializing input/output bindings, and providing custom handler boilerplates. charpente
also offers a high-level interface to htmltools
(the workhorse that converts R code to web-friendly HTML).
We’ll cover both of these texts more in the frameworks section.
Development Environments
The two integrated development environments (IDEs) I will be demonstrating are RStudio and Positron.
RStudio is a popular integrated development environment (IDE) that streamlines many R package development tasks. I’d previously connected this IDE to the definitions above for R package and Shiny app-packages. Specifically, the package development tools provided in the Build pane and the devtools
package.
Positron is Posit’s new integrated development environment (IDE) designed to improve productivity and performance across multiple programming languages. Building on RStudio’s success, Positron offers a sleek, user-friendly interface while keeping powerful tools for debugging, profiling, and interactive visualizations.
Most of the book will focus on developing Shiny app-packages in RStudio, because Positron is under active development. When I’m including information specific to particular IDE, I will use icons to differentiate Positron from RStudio ( vs. ).
Other tools
Developing R packages in RStudio or Positron is not required. There are alternative IDEs and tools, and many developers employ these setups (VS Code, PyCharm, Jupyter Lab, Colab, etc). Package development outside RStudio would look almost identical to development in the IDE:
Create the package structure (
R/
folder for.R
scripts,man/
folder for documentation,data/
folder for datasets, etc.)Create
DESCRIPTION
andNAMESPACE
files, etc.Ensure the package can be installed and loaded into an R session.
The development workflow functions we’ll cover work just about anywhere you can execute R code (i.e., roxygen2::roxygenize()
, devtools::load_all()
, devtools::install()
, etc.).
How to read this book
Transitioning from programming in R to building Shiny applications and writing R packages presents a steep learning curve. The chapters in this book are aimed flattening the package development portion of that curve. As with any new skill, app-package development involves new mental models, concepts, terminology, habits, and details. If you find yourself getting frustrated, I recommend the 15 minute rule:
“By forcing yourself to try for 15 minutes, you gain a deeper understanding of what you’re troubleshooting so that, even if you don’t fix it in 15, next time you’re in a better position to troubleshoot than you were the last time.
And by forcing yourself to ask for help after 15, you not only limit the amount of banging-your-head time, but you also get to see how the other person solves the problem while all the details are still fresh in your mind, so that you’ll more likely have a deeper understanding of why what you were doing to fix it wasn’t working, and why the ultimate solution actually worked.” - Hacker News, 2013
The chapters in this book (roughly) represent the steps of R package development, but through the lens of an existing Shiny application.4 Each topic can be applied to creating a new app-package, but–in my experience–many Shiny developers have existing applications they’d like to convert into an R package.
Introduction covers the development of a Shiny app project and it’s gradual progression of complexity to warrant an R package:
1 Whole app game is a ‘whole game’ for the development of a toy app-package. This chapter gives a high-level overview of the app-package development workflow.5
In 2 Shiny we’ll dive into shiny development, focusing on the files and folders found in most Shiny applications.
R packages are introduced in 3 Packages, and it covers the differences between Shiny app projects, R packages, and Shiny app-packages.
4 Development introduces
devtools
and the app-package development workflow.
The app-packages applies the key components of R package development to a Shiny app. These sections aren’t likely to change anytime soon.
5 Documentation covers documenting the application’s utility functions, modules, UI, server, and standalone app function using
roxygen2
.Managing dependencies (both imports and exports) using the
NAMESPACE
file is introduced in 6 Dependencies7 Data discusses the storage, format, and documentation of data files your app-package.
There are multiple ways to launch an application from an app-package. 8 Launch covers options to include in the
app.R
file and your standalone app function.9 Resources covers the many uses of the
inst/
folder in R packages. This chapter also covers how to add external files and resources to your application.
While developing your application, you’ll want to ensure it’s features are documented and tested. The Tests section covers testing:
Before running any tests we need to set up the test suite in our app-package. 14 Test suite briefly covers setting up the testing infrastructure with
testthat
.Knowing what features to implement and what tests to develop reduces the chances of writing code that doesn’t address a user needs. 15 Specifications discusses how to identify user specifications, features, and functional requirements. It also briefly introduces behavior-driven development.
16 Test tools covers how to include testing tools (fixtures and helpers) in your test suite to ensure isolated yet controllable test conditions.
Reactivity makes testing modules tricky. In 17 Testing modules, I’ll cover some strategies and approaches for verifying that your modules are communicating correctly with Shiny’s
testServer()
function.18 System tests introduces performing system (or end-to-end) tests in you app-package with the
shinytest2
package.
After you’ve developed your Shiny App-Package, you’ll likely want to deploy it (or put it ‘into production’). A selection of popular methods are covered in Deploy:
20 Docker explains how build Docker images and containers using Docker desktop. These topics are also covered in 23 golem.
21 GitHub Actions covers continuous integration (CI) / continuous deployment (CD) for Shiny app-packages using GitHub Actions.
22 pkgdown websites are an excellent way to enhance it’s visibility and usability of your app-package (and it’s made seamless with
usethis
and GitHub actions (see 22.4 Deploying your site)).
If you’re Googling ‘what is the best way to build a Shiny application?’ you’ll eventually encounter a Shiny framework. This section contains the development workflow and methods for three popular Shiny application frameworks (golem
, leprechaun
, charpente
and rhino
).
23 golem covers developing an application using the
golem
framework (which is introduced in Engineering Production-Grade Shiny Apps).For developers looking for a ‘lightweight’ version of the
golem
package, 24 leprechaun introduces theleprechaun
package and development workflow25 charpente is the Shiny framework introduced in Outstanding User Interfaces with Shiny.
26 rhino covers how to build a
rhino
application (which is not technically a package, but is still worth including based on it’s popularity and features).
The special topics section includes a handful of topics on development, storing and retrieving data, reading error outputs, and keeping track of dependencies.
29 App data explores the differences between and use of
shiny::reactiveValues()
andsession$userData
.30 Stack traces (this chapter is under construction)
31 Dependency hell (this chapter is under construction)
Acknowledgments
This book is the result of multiple discussions with 1) Shiny developers who were new to writing R packages, 2) R package authors who were learning Shiny development and testing, and 3) new R users who wanted to build a robust and scalable application. Shiny App-Packages wouldn’t have been possible without the contributors below (and I am deeply grateful for all of their help!).
- Henry Bernreuter & Elizabeth Marshallsay for the initial discussions that created the outline for this book
- Andrew Bates for being an exemplary developer and professional, quietly building outstanding UIs, applications, and packages
- Eric Simms for asking so many great questions, reviewing chapters, and giving phenomenal feedback
- Eric Nantz6 for his R podcast, Shiny developer series, workshops, and everything else he does for the Shiny community
- Philip Bowsher for everything he does for the R/Pharma conference and community
- Ted Laderas for his excellent gRadual intRoduction to Shiny course and insightful blog posts
- Jennifer Bryan and Hadley Wickham for their posit::conf(23) package development masterclass workshop.
- Maya Gans for having multiple conversations and Shiny modules and package dependencies
- Leon Samson for his feedback on the testing chapters
Testing Shiny apps requires additional packages and tools to ensure an application’s reliability and performance.↩︎
The ‘Converting an existing app’ chapter provides an example of converting a Shiny app into an R Package. However, many of the helpful package development tools aren’t available (i.e.,
roxygen2
tags,NAMESPACE
imports/exports, tests, vignettes, etc.).↩︎golem
apps are built as packages. Still, EPGSA assumes the reader is ‘comfortable with building an R package.’ (if you’re familiar with package development, EPGSA is an excellent resource).↩︎The original code and data for the application in this book comes from the Building Web Applications with Shiny (BWAS) course.↩︎
R Packages, 2ed, has a similar chapter that covers developing standard R packages.↩︎