Publisher Guide

Complete reference for building and distributing Shiny app deployments with Shiny ShareBridge

This guide covers every feature of the Shiny ShareBridge Publisher in depth. For a quick walkthrough, see Getting Started.

Launching the Publisher

Method	When to use
`PublishApp.hta`	Default — opens hidden, no console window
`publish.bat`	Fallback if `.hta` files are blocked by Group Policy

Both open the same Shiny-based Publisher UI in your default browser.

Note

When the same Publisher UI runs on Posit Connect Cloud or Hugging Face Spaces, it is in hosted inspector mode. Hosted sessions can upload a local app folder through the browser, inspect it, and return a generated zip, but they cannot browse arbitrary folders on your computer or create Portable R from your local Windows installation.

Important

Always launch from inside the Shiny ShareBridge framework root — not from inside a deployed app folder.

Source app

Supported layouts

Shiny ShareBridge supports two standard Shiny structures:

Single-file:

my_app/
└── app.R

Split:

my_app/
├── ui.R
└── server.R

Supporting folders are copied automatically: www/, R/, modules/, data/, config/, and any other files or subdirectories in the source.

Hosted source upload

In hosted mode, click Browse… under App folder to open your browser’s local folder picker. The selected folder is uploaded into the hosted runtime and ShareBridge uses that server-side copy. The Upload zip instead fallback is available when a browser or environment does not support folder uploads.

Hosted mode does not use a free-form local source path because a hosted server cannot read C:\... or \\server\... paths from your machine unless those files are uploaded.

Validation badge

When you select a source folder, Shiny ShareBridge immediately validates it and shows a badge:

🟢 app.R found or ui.R + server.R found — valid, build can proceed
🔴 Error message — folder is missing required entry points, build is blocked

Package detection

How it works

Shiny ShareBridge scans all .R, .Rmd, and .qmd files in the source folder for:

library(pkg) and require(pkg)
pkg::function() and pkg:::function()

Primary scanner: renv::dependencies() when renv is installed Fallback: built-in regex parser

shiny is always included regardless of what the scanner finds.

What the scanner misses

Pattern	Example
Dynamic loading	`lapply(pkgs, library, character.only = TRUE)`
String-constructed names	`library(paste0("data", ".table"))`
Scripts sourced from outside the app folder	`source("../shared/helpers.R")`

Add these manually in the Additional packages box (one per line).

Dependency review

The Publisher UI also shows a dependency review below the detected package list. It highlights common signals such as:

Report packages (rmarkdown, knitr, quarto, pagedown, officer, flextable) that may need Pandoc support
Data access packages (DBI, odbc, RSQLite, pool, arrow, duckdb) that may need credentials or runtime data paths
Interactive UI packages (DT, plotly, leaflet, htmlwidgets, bslib) that should be bundled like any other dependency
System dependency risks (sf, terra, rJava, magick, curl, openssl, xml2, chromote, webshot2, V8, units, s2) that may need external libraries, Java, browser tooling, or OS support
Authentication or secret-handling packages (httr, httr2, gargle, AzureAuth, keyring, blastula) that should be reviewed for approved runtime credential handling

Output options

Output folder

The output folder is where the complete deployable folder is written. It is auto-filled as <parent_of_framework>/<app_name>_deploy but you can set it anywhere.

Warning

The output folder is completely reset on every build. Do not point it at a folder containing other important files.

Create zip file

When enabled, Shiny ShareBridge zips the output folder after building. The zip file appears at <output_dir>.zip and is available for download directly from the Publisher UI.

Important

If users should run the zip without installing R, create portable R first and confirm the zip contains the generated R/ folder. A zip of only the Shiny app files is not a complete ShareBridge deployment.

Build offline repo

When enabled, Shiny ShareBridge downloads a copy of all bundled packages into a repo/ folder inside the deployment. At runtime, run.R installs from this local repo first, falling back to CRAN only if the local repo is missing.

Use this when your end users have no internet access.

Hosted output

In hosted mode, the output folder is generated automatically inside the hosted runtime. The result is returned as a zip download from the build success bar. Hosted sessions cannot select a folder on your computer as the output destination.

Recipes, examples, and preflight

Workflow setup

The I want to selector applies a starting setup for common goals:

Goal	What it prepares
Inspect an app	Hosted-friendly inspection settings
Build for SharePoint users	Zip output and file-share-oriented build settings
Build for users without R	Zip output plus offline/review settings, with Portable R highlighted
Build a report app	Pandoc and rmarkdown helper support
Prepare an IT handoff	Report/checklist-oriented settings

Build recipes

The Recipes and examples panel applies common option sets without changing the selected source folder:

Recipe	Use
SharePoint offline deployment	Zip output plus offline repo for file-share distribution
Small app, no portable R	Lightweight build when target machines already have compatible R
Report app with Pandoc	Turns on Pandoc and rmarkdown helper support
Hosted validation only	Hosted review before a local production build
Upload inspection only	Quick source/package inspection in hosted mode

Example apps

The built-in examples create temporary Shiny apps for quick testing:

Example	What it tests
Simple app	Basic Shiny app packaging
Data app	Bundled data files under `data/`
Report app	`rmarkdown`/`knitr` detection and Pandoc-related options

Preflight checks

The Preflight panel checks whether the source is valid, the app name and output are set, build R is available, packages are detected, Portable R is present, app files are visible, and obvious local path risks are present in .R, .Rmd, or .qmd files.

The portability scanner flags hard-coded Windows or network paths, setwd(), interactive file choosers, references outside the app folder, environment-based credential references, and possible hard-coded secrets.

Warnings do not always block builds, but they should be reviewed before distributing the output to users.

Readiness score and reports

The top readiness panel combines preflight checks and dependency advisories into a score:

Status	Meaning
ShareBridge-ready	Core checks are passing
Needs review	Build may proceed, but warnings should be reviewed
Blocked	A required input or build prerequisite is missing

The Preflight panel can download:

Readiness report - Markdown summary of score, packages, preflight checks, and next steps
IT checklist - Markdown handoff notes covering runtime, local ports, launchers, data paths, packages, and warning items

After a successful build, the success bar also offers User instructions, a plain-text handoff file for end users.

Advanced app features

Enable write-capable app mode

Ensures selected app subdirectories exist inside the deployed app/ folder. Useful for apps that write to data/, uploads/, cache/, or tmp/.

When you enable this option, Shiny ShareBridge scans the source folder for subdirectories and presents them as checkboxes. Select the ones that need to exist (and be writable) in the deployment.

Note

This only creates the directories — it does not modify your app code. Your app must still reference and write to those folders.

Include Pandoc runtime

Creates a pandoc/ stub folder in the deployment and adds R Markdown support packages (rmarkdown, knitr, etc.) to req.txt.

At runtime, if pandoc/pandoc.exe is present, Shiny ShareBridge sets RSTUDIO_PANDOC automatically so rmarkdown finds it.

Important: Shiny ShareBridge does not copy Pandoc automatically. After building, place a Pandoc installation into the pandoc/ folder manually. Download from pandoc.org.

Shiny ShareBridge links to the official Pandoc install page and release downloads from the Publisher UI. This keeps the framework small and lets publishers choose the version their environment allows. If you place pandoc.exe and its supporting files under the deployment pandoc/ folder, Shiny ShareBridge will use that bundled copy at runtime.

The Publisher UI shows whether pandoc/pandoc.exe is currently present in the framework. If it is missing, the app can still build a Pandoc-ready stub, but report rendering that requires Pandoc will need the executable added before distribution.

External data directory (DATA_DIR)

For apps that write data which should not live inside the synced SharePoint folder (e.g. frequently written outputs, user uploads), set a DATA_DIR path here.

Accepts UNC paths (\\server\share\AppData) or local paths
Written to app_meta.cfg as DATA_DIR=
Available to your app at runtime as the environment variable SHAREBRIDGE_DATA_DIR

Example in your app code:

data_dir <- Sys.getenv("SHAREBRIDGE_DATA_DIR", unset = "data")

In hosted mode, DATA_DIR is only a runtime path recorded for the eventual deployed Windows app. To bundle data files during a hosted build, put the files inside the uploaded app folder or zip.

Build summary panel

Before you click Build deployment, a summary panel shows a snapshot of what will be built:

Field	Description
App name	Display name used in launchers
App ID	Sanitized ID used for port derivation and URLs
Packages	Total count (detected + extras)
Portable R	Whether `R-portable-master/` is found in the framework
Zip output	Whether a zip will be created
Offline repo	Whether a local CRAN mirror will be built
Pandoc stub	Whether the pandoc folder will be created
DATA_DIR	External data path if set

Build progress

The overlay tracks each build phase with a live percentage, step label, and elapsed time:

Binary installs show the current package being downloaded
Source compilation shows the C/C++ compile percentage and triggers a shimmer animation on the progress bar — this is normal and expected for packages that don’t have a Windows binary
Elapsed time helps set expectations on first builds

Tip

Source compilation only happens on the first build or after an R version upgrade. Subsequent builds install binaries from the cache.

Health check

After every successful build, Shiny ShareBridge runs an automatic health check:

Check	Critical
Required files present (`LaunchApp.hta`, `run.bat`, `run.R`, `req.txt`, `app_meta.cfg`, `VERSION`)	Yes
`app/` directory exists	Yes
`packages/` directory exists	Yes
All packages in `req.txt` are present in `packages/`	Yes
Portable R bundled (`R/`)	No (warning only)
`pandoc.exe` present when `pandoc/` folder exists	No (warning only)

Critical failures (red) mean the deployment will not work. Warnings (amber) mean reduced functionality.

Test launch

The Test launch button in the success bar opens LaunchApp.hta from the output folder directly — identical to what an end user does. Use it to verify the app starts cleanly before copying to SharePoint.

Saved profiles

Build settings can be saved as named JSON profiles stored in <framework_root>/profiles/.

Action	Description
Save	Saves all current form fields under the given name
Load selected	Restores all fields from the selected profile
Delete selected	Removes the profile JSON file

Note

Profiles store absolute paths for source_dir and output_dir. These will need updating if the profile is used on a different machine.

In hosted mode, profiles save reusable options but do not save uploaded files or generated server output paths. Upload the app folder again for each hosted session.

Publisher logs

All build output is written to <framework_root>/logs/publisher/ as timestamped .log files. Logs older than 30 days are cleaned automatically.

From the Publisher logs panel you can:

Browse all saved log files
Preview the last 250 lines of any log
Delete individual or all logs
Download a diagnostics zip with summary notes, readiness report, user instructions, IT checklist, current logs, selected saved log, package list, preflight results, and health-check JSON when available

Logs contain the full build subprocess output — useful for diagnosing failed installs, missing packages, or robocopy errors.

Portable R setup

Why portable R?

Without bundled portable R, end users must have R installed. Portable R eliminates that requirement entirely.

Folder structure

Folder	Purpose
`R-portable-master/`	Cold source copy — used during publishing
`R-portable/`	Live runtime copy — used for local launch and testing

The split avoids Windows DLL locking: when you publish, robocopy reads from the cold R-portable-master/ while R-portable/ may be in use.

What gets stripped

To keep deployments a manageable size, strip_r.R removes:

HTML help files and vignettes
Translations and locale files
C headers and development files
Test suites
Tcl/Tk runtime (optional — keep with Keep Tcl/Tk checkbox)
Package-level documentation (optional — control with Strip package docs checkbox)

All runtime code, DLLs, NAMESPACE, and DESCRIPTION files are preserved.

Creating portable R

Install a full R on the publisher machine
Open the Framework setup panel in the Publisher UI
Browse to the full R installation folder
Click Create portable R
Wait for the green success bar

You only need to do this once per R version.

Use the official R for Windows download as the source for the full R installation. Shiny ShareBridge can strip and bundle that local installation into R-portable-master/, but the project does not ship a prebuilt portable R binary by default. If you redistribute deployments with bundled R, retain the applicable R license notices; R is licensed under GPL-2 or GPL-3.

Hosted sessions cannot create Portable R because they cannot browse or package the publisher’s local Windows R installation. Use the local Windows Publisher UI for this step.