Build Stateless Web Apps with 'plumber2'

A scaffolding and deployment toolkit for building stateless web applications in R on top of the 'plumber2' web framework (< https://plumber2.posit.co/>). The UI is authored with 'bslib' and compiled to a static HTML asset at build time, while 'plumber2' serves the assets and exposes JSON API routes. Provides functions to scaffold app skeletons, run them locally, and generate Dockerfiles and images suitable for 'ShinyProxy' or plain Docker.

aurora

Shiny-style authoring, stateless API deployment.

aurora lets you build a web app the way you'd build a Shiny app — author the UI in R with bslib, scaffold the project, run it locally with hot-reload — but it compiles the UI to a static index.html at build time and lets plumber2 serve that UI plus your JSON API. There's no reactive server, no per-user R process, and no sticky sessions: the app is stateless and scales horizontally behind a load balancer, ShinyProxy, or plain Docker.

• 🎨 UI in R — author with bslib + _brand.yml; ship a static HTML asset.
• ⚡ Stateless — plumber2 serves the assets and JSON routes; scale by adding containers.
• 🧩 Convention over config — fixed folders, no required manifest.
• 🔐 Batteries, opt-in — JWT-cookie auth, a hot-reloading data store, OpenTelemetry.
• 🐳 One-command deploy — generate a Dockerfile (debian or alpine) or a ShinyProxy spec.

What an app looks like

A route handler is just an annotated function — its URL is the annotation:

# routers/iniciativas.R   ->   GET /api/iniciativas/data
#* @get /api/iniciativas/data
#* @serializer json
function() {
  dados <- aurora_data_get(store, "iniciativas")   # hot-reloaded from disk
  list(data = dados, municipios = aurora_unique(dados$municipio))
}

The UI is plain bslib, compiled once to www/index.html:

# build_ui.R   ->   www/index.html (static, built by aurora_build_ui())
build_ui <- function() {
  bslib::page_fillable(
    theme = bslib::bs_theme(version = 5, brand = TRUE),
    aurora_component("/api/iniciativas/data", id = "tabela")  # wires a div to the endpoint
  )
}

build_ui.R (bslib + _brand.yml) ──aurora_build_ui()──▶ www/index.html (static)

Browser ◀──▶ plumber2 server (aurora_app)
              ├── serves www/ (static UI + core.js/app.js)
              ├── routers/*.R        → JSON
              ├── helpers/*.R         (sourced first: config, db, auth, store)
              └── optional JWT-cookie auth guard

Installation

# From GitHub — latest release (recommended):
# install.packages("pak")
pak::pak("aurora-govpe/[email protected]")

# Development version (main branch):
pak::pak("aurora-govpe/aurora-rpkg")

# From CRAN (once published):
install.packages("aurora")

remotes/devtools work too: remotes::install_github("aurora-govpe/[email protected]").

Quick start

library(aurora)

aurora_create_app("meu_app", template = "minimal")
aurora_add_route("iniciativas", dir = "meu_app")   # -> routers/iniciativas.R
aurora_run("meu_app")                              # http://127.0.0.1:8000 (docs at /__docs__)

aurora_run("meu_app", watch = TRUE) rebuilds the static UI on change. Theming is a _brand.yml consumed by bslib; auth, data, and telemetry are opt-in (template = "auth", aurora_data_store(), aurora_run(otel = TRUE)).

Canonical app layout (convention; no manifest required)

<app>/
├── api.R            # entry: aurora::aurora_run("."), host/port from env
├── build_ui.R       # defines build_ui() -> htmltools tag; sources ui_modules/
├── helpers/         # *.R sourced before routers are parsed (config, db, auth…)
├── routers/         # plumber2 annotated handlers; URL = annotation path
├── ui_modules/      # ui_*.R partials
├── www/             # static assets: js/core.js (runtime), js/app.js, style.css, images/
├── data/config.yml  # app config (config package)
├── _brand.yml       # optional: bslib theming (color/type/logo)
├── _aurora.yml      # optional: overrides name/engine/auth/packages/attach/statics
└── Dockerfile       # generated by aurora_dockerfile()

Deploy

aurora_dockerfile("meu_app")                        # flavor = "debian" (default)
aurora_dockerfile("meu_app", flavor = "alpine")     # tiny image, source-built
aurora_build_image("meu_app", tag = "org/meu_app:latest", push = TRUE)

The container serves the prebuilt static UI, so neither flavor installs bslib/shiny at runtime. aurora_build_image() targets linux/amd64 by default, so images built on an Apple Silicon Mac run on x86-64 servers (pass platform = NULL for a host-native build).

Rule of thumb: debian for fast CI and rich/geo dependencies; alpine when image size matters most and you can absorb longer builds.

Apps that share static assets (logo, JS libraries, CSS) can serve them from one server-side directory via _aurora.yml:

# _aurora.yml — serve /srv/aurora-shared at /assets (alongside www/ at /)
statics:
  /assets: /srv/aurora-shared

Mount the directory as a volume (-v /srv/aurora-shared:/srv/aurora-shared:ro) and every app picks up changes from one place. See vignette("deploy").

Core functions

See the Get started article, the Gallery, and the function reference.

Design decisions

• plumber2 only. Each handler's URL comes from its annotation.
• Thin JS runtime. core.js is aurora's basics; app.js and aurora_component() keep rendering in the app, not the package.
• Pluggable auth. A JWT-cookie @header guard, never in aurora_app()'s core path.
• Convention over manifest. Fixed folders; _aurora.yml optional.
• Theming via brand.yml. bslib consumes _brand.yml at build time.

Authors

• Andre Leite — maintainer ([email protected])
• Marcos Wasilew · Hugo Vasconcelos · Carlos Amorin · Diogo Bezerra · Júlia Nascimento Barreto

Developed by the NGR-Dados team (SEPLAG-PE) with UFPE.

License

MIT © aurora authors. Contributions welcome via issues and pull requests.