Preface

Published

2024-07-03

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

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 conversion into 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.

App-packages applies the key components of R package development to a Shiny app:

  • 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  Dependencies

  • 7  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  External files 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. 10  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. 11  Specifications discusses how to identify user specifications, features, and functional requirements. It also briefly introduces behavior-driven development.

  • 12  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 13  Testing modules, I’ll cover some strategies and approaches for verifying that your modules are communicating correctly with Shiny’s testServer() function.

  • 14  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)).

Shiny apps often contain non-R code files, such as CSS or JavaScript, for custom visualizations, widgets, enhanced HTML reports, etc. Including these files in your app-package (and then accessed from your R code) is covered in Code:

  • ?sec-html (this chapter is under construction)

  • ?sec-css introduces where to store code used for styling your application (this chapter is under construction)

  • 29  JavaScript (this chapter is under construction)

  • ?sec-style (this chapter is under construction)

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

The special topics section includes a handful of topics on development, storing and retrieving data, reading error outputs, and keeping track of dependencies.

  • ?sec-debug covers strategies and tricks for debugging errors and exploring reactivity in your Shiny app.

  • 31  App data explores the differences between and use of shiny::reactiveValues() and session$userData.

  • 32  Stack traces (this chapter is under construction)

  • 33  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!).

  1. Testing Shiny apps requires additional packages and tools to ensure an application’s reliability and performance.↩︎

  2. 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.).↩︎

  3. 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).↩︎

  4. The original code and data for the application in this book comes from the Building Web Applications with Shiny (BWAS) course.↩︎

  5. R Packages, 2ed, has a similar chapter that covers developing standard R packages.↩︎

  6. Eric’s LinkedIn↩︎