Reference

Complete reference for all ShareBridge configuration files, CLI arguments, and runtime environment variables

Configuration files

`app_meta.cfg`

Written by the publisher, read by run.bat and run.R at launch time. Plain KEY=VALUE format, one entry per line. Lines starting with # are ignored.

Key	Type	Default	Description
`APP_NAME`	string	`Shiny App`	Human-readable display name shown in the launcher window title and loading screen
`APP_ID`	string	`ShinyApp`	Sanitized identifier used for port derivation, log file naming, and the loopback URL
`PREFERRED_PORT`	integer	derived	Preferred local port in the range 3400–4400, derived deterministically from APP_ID. Falls back to a random port if unavailable.
`HOST`	string	`127.0.0.1`	Loopback address. Do not change unless you have a specific reason.
`DATA_DIR`	path	unset	Optional external data directory for app data that should not live in the synced deployment folder. Exposed as `SHAREBRIDGE_DATA_DIR` at runtime.

Example:

APP_NAME=Sales Dashboard
APP_ID=Sales_Dashboard
PREFERRED_PORT=3741
HOST=127.0.0.1
DATA_DIR=\\server\share\SalesDashboard\data

`req.txt`

Plain text list of required R packages, one per line. Written by the publisher during the build. Lines starting with # are treated as comments.

run.R reads this file and installs any listed packages that are missing from the bundled library.

Example:

# Auto-generated by ShareBridge
dplyr
DT
ggplot2
shiny

Note

Do not edit req.txt manually after building — the packages folder must match. Re-run the build to change dependencies.

`VERSION`

Written by the publisher after each build. Read by run.R for the R version mismatch guard.

Key	Description
`AppName`	App display name
`BuiltAt`	Build timestamp (YYYY-MM-DD HH:MM:SS tz)
`RVersion`	Full R version string (e.g. `4.5.1`)
`RVersionMajorMinor`	Major.minor only (e.g. `4.5`). Used by the mismatch guard.
`Platform`	R platform string (e.g. `x86_64-w64-mingw32`)
`PackageCount`	Number of bundled packages
`HasPortableR`	`true` when portable R was bundled

`req_extra.txt`

Optional. Place this file in the source app folder or the framework root to add packages that the scanner cannot detect. Same format as req.txt.

ShareBridge merges it with the auto-detected package list during the build. It is not required — you can also add extra packages interactively in the Publisher UI.

`packages_manifest.tsv`

Written after every build by build_packages.R. Tab-separated file listing every bundled package and its installed version. Used for auditing and troubleshooting.

Runtime environment variables

Variables set by run.R and run.bat that your Shiny app can read:

Variable	Set by	Description
`SHAREBRIDGE_DATA_DIR`	`run.R`	Value of `DATA_DIR` from `app_meta.cfg`. Unset if DATA_DIR is not configured.
`RSTUDIO_PANDOC`	`run.R`, `run.bat`	Path to the local `pandoc/` folder. Set automatically when `pandoc/pandoc.exe` is present.
`SHINY_LOG_LEVEL`	`run.R`	Defaults to `INFO`. Override with the same env var before launching.

Example — reading DATA_DIR in your app:

data_dir <- Sys.getenv("SHAREBRIDGE_DATA_DIR", unset = "data")
user_file <- file.path(data_dir, "uploads", "latest.csv")

Library path order

run.R prepends the following to .libPaths() before launching the Shiny app:

<deployment>/packages/ — bundled package library
<deployment>/R/library/ — portable R base library (if present)
System .libPaths() — existing user/system libraries

Packages are resolved in this order, so bundled versions always take precedence.

Port assignment

Each app gets a deterministic preferred port in the range 3400–4400, derived from the App ID:

derive_port <- function(app_id, range_start = 3400L, range_size = 1001L) {
  raw  <- charToRaw(app_id)
  hash <- sum(as.integer(raw) * seq_along(raw)) %% range_size
  as.integer(range_start + hash)
}

This ensures two different apps published through ShareBridge will not collide on the same port by default.

If the preferred port is unavailable at launch, run.R falls back to httpuv::randomPort().

Launch URL format

http://sharebridge-{app_id_lowercase}.localhost:{port}

Example: App ID Sales_Dashboard on port 3741 opens at:

http://sharebridge-sales_dashboard.localhost:3741

CLI reference — `publish_app.R`

publish_app.R can be called directly from the command line as well as from the Publisher UI.

Rscript --vanilla build/publish_app.R \
  --source_dir   "C:/path/to/my_app" \
  --output_dir   "C:/path/to/output" \
  --app_name     "My Dashboard" \
  --framework_dir "C:/path/to/ShareBridge" \
  --zip \
  --build_offline_repo \
  --data_dir     "\\server\share\AppData"

Argument	Required	Description
`--source_dir`	Yes	Path to the Shiny app source folder
`--output_dir`	Yes	Path where the deployment folder will be created
`--app_name`	No	Display name (defaults to basename of output_dir)
`--framework_dir`	No	ShareBridge root directory (auto-detected from script location)
`--req_extra_file`	No	Path to an extra requirements file to merge
`--app_features_file`	No	Path to a JSON file with advanced feature flags
`--zip`	No	Flag — create a zip archive of the output folder
`--build_offline_repo`	No	Flag — build a local CRAN mirror in `repo/`
`--data_dir`	No	External data directory path written to `app_meta.cfg`
`--preferred_port`	No	Override the auto-derived port
`--cran_repo`	No	CRAN mirror URL (default: `https://cloud.r-project.org`)
`--verify_load`	No	Flag — load-test all bundled packages after install (default: true)

CLI reference — `strip_r.R`

Rscript strip_r.R \
  --r_source "C:/Program Files/R/R-4.5.1" \
  --framework_dir "C:/path/to/ShareBridge" \
  --strip_pkg_docs \
  --keep_tcltk

Argument	Description
`--r_source`	Path to a full R installation to strip
`--framework_dir`	ShareBridge root — output goes to `R-portable-master/` here
`--strip_pkg_docs`	Flag — remove documentation from base packages (recommended)
`--keep_tcltk`	Flag — preserve the Tcl/Tk runtime (larger output, needed for tcltk package)

Deployment folder structure

MyApp_deploy/
├── LaunchApp.hta          # User launcher (HTA)
├── run.bat                # Runtime launcher (batch)
├── run.R                  # Runtime entry point
├── app_meta.cfg           # App metadata
├── req.txt                # Required packages list
├── VERSION                # Build metadata
├── README_User.txt        # Plain-text user instructions
├── README_Publisher.txt   # Plain-text publisher notes
├── packages_manifest.tsv  # Bundled package manifest
├── app/                   # Shiny app code
├── packages/              # Bundled CRAN packages
├── build/
│   └── build_packages.R
├── logs/                  # Runtime logs
├── R/                     # Portable R (optional)
├── pandoc/                # Pandoc runtime stub (optional)
└── repo/                  # Offline CRAN mirror (optional)

Known limitations

Limitation	Notes
OneDrive sync lag	Users may launch before files finish syncing. App will fail with “package not found” until sync completes.
Path length limit	Windows has a 260-character path limit. Keep deployment folder names short.
HTA file blocking	Some environments block `.hta` via Group Policy. Use `run.bat` as a fallback.
Writable data in synced folders	Frequently written files should use `DATA_DIR` rather than living inside the synced deployment folder.
Pandoc not auto-bundled	The publisher creates the stub folder but does not download Pandoc. Place `pandoc.exe` manually.
Source compilation requires Rtools	Packages without Windows binaries must be compiled. Rtools must be installed on the publisher machine.

Configuration files

app_meta.cfg

req.txt

VERSION

req_extra.txt

packages_manifest.tsv

Runtime environment variables

Library path order

Port assignment

Launch URL format

CLI reference — publish_app.R

CLI reference — strip_r.R

Deployment folder structure

Known limitations

`app_meta.cfg`

`req.txt`

`VERSION`

`req_extra.txt`

`packages_manifest.tsv`

CLI reference — `publish_app.R`

CLI reference — `strip_r.R`