Building robust, modular dashboards with internal packages and Posit

You are assigned to maintain a dashboard someone on your team has graciously left you, and the users of this dashboard ask you to add a new feature. Fine, you think. “The data for this dashboard doesn’t look terribly complex. I’ll just step in where so-and-so left off and add that feature easily!”

Minutes quickly turn into hours as you realize that the last developer coded an entirely different way than you do. It will take days of refactoring just to understand what their code is trying to do, let alone add a new feature. Eventually, you scrap their entire dashboard and decide to rebuild it.

Or perhaps you have incoming hires of fresh developers who have never worked with {shiny} before. Can you trust that the training you have (if any) is sufficient and will prepare them to build production-ready dashboards independently?

This was the two-pronged challenge facing our team a few years ago. We needed to completely overhaul old dashboards while also training staff on how to build tools that help drive insights for the company. We quickly realized that we needed to decrease the time spent building dashboard frameworks for our new members and ensure that anyone taking over another dashboard could easily modify them.

One of the major advantages of open source is the vast community that enables the widespread sharing of knowledge. Community members collaborate to develop tools that help solve problems. Sharing those tools allows others to benefit from their contributions.

Our journey started with {golem}(opens in a new tab), an open-source package built by the great team at ThinkR(opens in a new tab). At a high level, {golem} turns your Shiny dashboards into a package framework and allows you to develop and deploy them exactly as you would an R package. This allows for better documentation, testing, robustness, etc. It’s a wonderful framework for engineering dashboards. However, the concepts themselves can be complex and technical. At the time, we knew this would be hard to explain (and implement) with our new developers.

Building upon the amazing {golem} package, we created a wrapper that abstracts away its technical side and sets defaults for our development workflow. We also set the defaults to include our company branding. We named this new internal package {graveler}.

Information on {graveler} can be found in the GitHub repository(opens in a new tab). Install the package using devtools:

    ``` R
    devtools::install_github("ghcarlalan/graveler")
    ```

A new option appears when you open a new project. You can set your package name, username, and display title in this dialogue box.

Creating this project will include all the files necessary to create your initial dashboard and theming. You will see three open files:

• 01_dev.R
• run_dev.R
• 02_deploy.R

The first file sets up the dependencies for deployment. These include the libraries you need to run your dashboard, a ‘golem.config’ system file, an ‘app.R’ file to deploy on Posit Connect, and a manifest file to use git-backed content within Posit Connect. You can adjust these to fit your workflow.

Once those steps are taken care of, execute the ‘run_dev.R’ file, and you will have your very own Shiny dashboard skeleton set up with minimal effort!

Video running run_dev.R(opens in a new tab)

The third file has helper functions we use to add environment variables (opens in a new tab) programmatically to our published work.

To add a new tab / module to your dashboard, you run ‘graveler::level_up(name = “foo”)’. This creates a module for your dashboard that contains sections for your UI and server code. At the bottom of each module, you will see three lines of code that you will copy and paste in their respective system files: ‘body.R’, ‘app_server.R’, and ‘sidebar.R’. The ‘level_up()’ function also creates a ‘fct’ file per {golem}’s recommendation, which incentivizes you to build functions for your dashboard modules to streamline debugging and testing.

From there, it’s just a matter of building modules and publishing with whatever workflow your team uses.

Video running sample graveler app(opens in a new tab)

Here at Snap, we use Posit’s Git-backed publishing feature(opens in a new tab) to seamlessly modify dashboards across our team and publish to Posit Connect. We have two Posit Connect servers: production and development, which allows us to test features or coding methods without messing with what our stakeholders are seeing. Posit Package Manager helps us share internally created packages (like {graveler}) and ensure that we all use the same packages/functions for our work.

With {graveler}, Posit Package Manager, and Posit Connect, developers are spending more time actually developing instead of spending time trying to spin up a Shiny framework. More importantly, they are all building dashboards the same way, reducing tech debt and simplifying code review. The ability to bring on new developers, integrate them into our workflow, and have them become almost instant contributors to our BI work with {golem} and {graveler} has been a great advantage to our team, our codebase, and our Sr. Developers’ sanities.