Skip to content

Latest commit

 

History

History
191 lines (152 loc) · 7.13 KB

README.md

File metadata and controls

191 lines (152 loc) · 7.13 KB
Raw

peeky Logo: a person peeking over someone who is coding close to their monitor.

R-CMD-check

The peeky package helps you extract, examine, and run the source code from Shiny applications that have been converted to run in the browser using Shinylive. It works with both standalone applications and Quarto documents containing Shinylive components through the quarto-shinylive extension, supporting both R and Python Shiny applications.

About Shinylive

Shinylive converts existing Shiny applications to run entirely in the web browser using WebAssembly versions of R (webR) and Python (Pyodide), eliminating the need for a computational server. This means all application files are accessible to users by design as they are downloaded to the user’s browser when the application is loaded.

The Shinylive ecosystem consists of four main components:

There Are No Secrets in Shinylive

The peeky package was developed to demonstrate a fundamental truth about Shinylive applications stressed by its developers: “There are no secrets.”

Unlike traditional Shiny applications where server-side code remains private, Shinylive apps run entirely in the web browser, making all associated files accessible to users. This includes the source code, data, and any other files used by the application. As a result, Shinylive applications are transparent by design.

This package was developed as part of ongoing discussions in STATS 290 about Shiny application security, transparency, and deployment options. It serves as a practical demonstration of the differences between traditional server-side applications and modern browser-based alternatives.

Installation

You can install the development version of peeky from GitHub with:

# install.packages("remotes")
remotes::install_github("coatless-rpkg/peeky")

Usage

To use the package, load it into your R session:

library(peeky)

Inside the package, there are three main functions:

Function Description
peek_shinylive_app() Universal function that handles both standalone apps and Quarto docs
peek_standalone_shinylive_app() Specifically for standalone Shinylive applications
peek_quarto_shinylive_app() Specifically for Quarto documents with Shinylive components

Extracting Shinylive Applications

We suggest using the peek_shinylive_app() function as it can handle both standalone Shinylive applications and Quarto documents with Shinylive components. For instance, if we take the main Shinylive extension website, we get:

peeky::peek_shinylive_app("https://quarto-ext.github.io/shinylive/")
#> 
#> ── Shinylive Applications ──────────────────────────────────────────────────────
#> 
#> ── Shiny for Python Applications ──
#> 
#> Run in Terminal:
#> shiny run --reload --launch-browser "/Users/ronin/Documents/GitHub/r-pkg/peeky/converted_shiny_app/app_1/app.py"
#> shiny run --reload --launch-browser "/Users/ronin/Documents/GitHub/r-pkg/peeky/converted_shiny_app/app_2/app.py"
#> shiny run --reload --launch-browser "/Users/ronin/Documents/GitHub/r-pkg/peeky/converted_shiny_app/app_3/app.py"
#> shiny run --reload --launch-browser "/Users/ronin/Documents/GitHub/r-pkg/peeky/converted_shiny_app/app_4/app.py"

This would be equivalent to if we ran the following:

peeky::peek_quarto_shinylive_app("https://quarto-ext.github.io/shinylive/")

By default, the extracted files will be placed in the current working directory under the converted_shiny_apps directory. Each application will be placed in a subdirectory named app_1, app_2, etc. If we want to specify a different output directory, we can do so by providing the output_path argument. We can also specify the output format as quarto to extract the files into a single Quarto document.

# Extract the Shinylive application into a different directory
peeky::peek_quarto_shinylive_app("https://quarto-ext.github.io/shinylive/", output_format = "quarto")
#> 
#> ── Quarto Document with Shinylive Applications ─────────────────────────────────
#> 
#> ── Setup and Preview Steps ──
#> 
#> Step 1: Install the Shinylive extension:
#> quarto add quarto-ext/shinylive
#> 
#> Step 2: Preview the document:
#> quarto preview "converted_shiny_apps.qmd"
#> 
#> ── Contents ──
#> 
#> • R applications: 0
#> • Python applications: 4

We can switch to the peek_standalone_shinylive_app() function if we know that the URL is a standalone Shinylive application. For example, if we take the example application used in the conversion tutorial from an app.R to an R Shinylive app on GitHub, we get:

peeky::peek_standalone_shinylive_app("https://tutorials.thecoatlessprofessor.com/convert-shiny-app-r-shinylive/")
#> 
#> ── Standalone Shinylive Application ────────────────────────────────────────────
#> Type: R Shiny
#> Run in R:
#> shiny::runApp("/Users/ronin/Documents/GitHub/r-pkg/peeky/converted_shiny_app")
#> 
#> ── Contents ──
#> 
#> .md files:
#> • README.md
#> .R files:
#> • app.R
#> 
#> Total files: 2
#> 
#> Location: '/Users/ronin/Documents/GitHub/r-pkg/peeky/converted_shiny_app'

License

AGPL (>= 3)

Evolution

This package represents a more refined and comprehensive approach compared to our earlier tutorial that focused solely on standalone R Shinylive applications.

Ethical Considerations

This package is for educational purposes. Users should:

  • Use responsibly
  • Respect intellectual property rights
  • Understand that viewable code doesn’t imply permission to reuse
  • Consider this when designing their own applications

Acknowledgements

Thanks to the Shinylive team and the webR and Pyodide teams for enabling browser-based data science.