https://github.com/insightsengineering/roxy.shinylive
roxygen2 extensions for shinylive
https://github.com/insightsengineering/roxy.shinylive
documentation r roxygen2 shiny shinylive webr
Last synced: 8 months ago
JSON representation
roxygen2 extensions for shinylive
- Host: GitHub
- URL: https://github.com/insightsengineering/roxy.shinylive
- Owner: insightsengineering
- License: other
- Created: 2024-08-19T13:58:50.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-04T12:51:40.000Z (12 months ago)
- Last Synced: 2025-06-04T20:16:28.803Z (12 months ago)
- Topics: documentation, r, roxygen2, shiny, shinylive, webr
- Language: JavaScript
- Homepage: https://insightsengineering.github.io/roxy.shinylive/
- Size: 8.03 MB
- Stars: 12
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: NEWS.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# roxy.shinylive
## Overview
This package provides a `roxygen2` extension that automatically takes the code
from the `@examples` tag and create an URL to the
[shinylive.io](https://shinylive.io/) service.
During the documentation build, a new section is added to the function manual
that contains the aforementioned link as well as an iframe to the application itself.
### shinylive.io
[shinylive.io](https://shinylive.io/) is a service that allows you to run
[Shiny](https://shiny.posit.co/) applications entirely in the browser, without
a dedicated server.
It uses WebAssembly via [WebR](https://docs.r-wasm.org/webr/latest/).
It has a sharing feature that allows you to encode the application code in the
URL.
This package does such encoding and returns the URL which can be used in
variety of ways (from raw URL to iframe in function manual - see examples
below).
## Install
```r
install.packages("roxy.shinylive")
```
Alternatively, you might want to use the development version.
```r
# install.packages("pak")
pak::pak("insightsengineering/roxy.shinylive")
```
## Usage
### Creating a URL manually
```r
code <- "\"Hello World\""
roxy.shinylive::create_shinylive_url(code, mode = "editor")
```
This returns the following URL:
### In the roxygen2 documentation
In your `DESCRIPTION` file, add the following:
```yaml
Roxygen: list(..., packages = c(..., "roxy.shinylive"))
```
Then in your package documentation:
```r
#' (docs)
#' @examplesShinylive
#' @examples
#' (example code with a Shiny app)
```
Which would produce a following output in your documentation:
```Rd
\section{Examples in Shinylive}{
\describe{
\item{example-1}{
\href{https://shinylive.io/r/app/#code=...}{Open in Shinylive}
\if{html}{\out{(custom JS)}}
\if{html}{\out{}}
}
\item{example-2}{
\href{https://shinylive.io/r/app/#code=...}{Open in Shinylive}
\if{html}{\out{(custom JS)}}
\if{html}{\out{}}
}
...
}
}
```
### In the vignettes
In your `DESCRIPTION` file, add the following:
```yaml
Suggests:
roxy.shinylive
```
Then in your vignette:
````Rmd
```{r shinylive_url, echo = FALSE, results = 'asis'}
# extract the code from knitr code chunks by ID
code <- paste0(c(
... # add more IDs if needed
knitr::knit_code$get("app"),
knitr::knit_code$get("shinyapp")
), collapse = "\n")
url <- roxy.shinylive::create_shinylive_url(code)
cat(sprintf("[Open in Shinylive](%s)\n\n", url))
```
```{r shinylive_iframe, echo = FALSE, out.width = '150%', out.extra = 'style = "position: relative; z-index:1"', eval = knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true")}
knitr::include_url(url, height = "800px")
```
````
See the package documentation for more details.
See the example implementation in the [`teal.modules.general`](https://insightsengineering.github.io/teal.modules.general/) or [`teal.modules.clinical`](https://insightsengineering.github.io/teal.modules.clinical/) packages.