Package {shinyelectron}

Title:	Export 'Shiny' Applications as Desktop Apps using 'Electron'
Version:	0.2.1
Description:	Provides tools to export 'Shiny' applications written in 'R' or 'Python' as standalone desktop applications using 'Electron'. The applications run as native, cross-platform programs. Depending on the runtime strategy chosen, end users do not need 'R' or 'Python' installed on their machine.
License:	AGPL (≥ 3)
URL:	https://r-pkg.thecoatlessprofessor.com/shinyelectron/, https://github.com/coatless-rpkg/shinyelectron
BugReports:	https://github.com/coatless-rpkg/shinyelectron/issues
Depends:	R (≥ 4.4.0)
Imports:	cli (≥ 3.6.6), fs (≥ 2.1.0), jsonlite (≥ 2.0.0), rappdirs (≥ 0.3.4), whisker (≥ 0.4.1), processx (≥ 3.9.0), stats, tools, utils, yaml (≥ 2.3.12)
Suggests:	testthat (≥ 3.3.2), mockery (≥ 0.4.5), quarto (≥ 1.5.1), renv (≥ 1.2.3), shinylive (≥ 0.5.0), withr (≥ 3.0.3)
VignetteBuilder:	quarto
SystemRequirements:	Node.js (>= 22.0.0), npm (>= 11.5.0)
Encoding:	UTF-8
Config/testthat/edition:	3
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-07-29 20:40:18 UTC; ronin
Author:	James Joseph Balamuta [aut, cre, cph]
Maintainer:	James Joseph Balamuta <james.balamuta@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-07 16:10:02 UTC

Configuration file name

Description

Configuration file name

Usage

CONFIG_FILENAME

Default configuration values for shinyelectron

Description

A list containing all default values used when no configuration file exists or when specific values are not provided.

Usage

SHINYELECTRON_DEFAULTS

Format

A named list with the following elements:

window_width

Default window width in pixels (1200)

window_height

Default window height in pixels (800)

server_port

Default local server port (3838)

app_version

Default application version ("1.0.0")

valid_app_types

Valid application types

valid_platforms

Valid target platforms

valid_architectures

Valid CPU architectures

valid_runtime_strategies

Valid runtime strategies

valid_container_engines

Valid container engines

splash

Default splash screen settings

tray

Default system tray settings

menu

Default application menu settings

updates

Default auto-update settings

preloader

Default preloader settings

container

Default container strategy settings

dependencies

Default dependency detection and runtime settings

logging

Default logging settings

signing

Default code-signing settings

lifecycle

Default lifecycle and prompt settings

installer

Default installer branding settings

runtime_versions

Maintained "latest known" runtime version pins (r, python, electron)

electron_toolchain

Pinned versions for electron-builder, electron-updater, electron-log (not config-settable)

dependencies$electron

Default Electron dependency settings; version is NULL (use pin) or a version string

dependencies$system_packages

Default system package list (NULL)

Check Shiny Application Readiness for Export

Description

Validates that a Shiny application can be built as an Electron app. Checks app structure, configuration, runtime availability, dependencies, and signing credentials. Reports issues without aborting.

Usage

app_check(
  appdir = ".",
  app_type = NULL,
  runtime_strategy = NULL,
  platform = NULL,
  sign = NULL,
  verbose = TRUE
)

Arguments

Value

Invisible list with:

Examples

# Check a bundled example app
app_check(example_app("r"))

# Check with explicit overrides
app_check(example_app("r"), app_type = "r-shiny", runtime_strategy = "system")

Detect an app's package dependencies

Description

Scans a Shiny app's source for the R or Python packages it uses, with the same detection shinyelectron applies at build time. This is useful before a shinylive build, in CI especially, because shinylive::export() compiles the WebAssembly bundle from the packages installed in the current session, so an app's dependencies must be installed before conversion.

Usage

app_dependencies(appdir, app_type = NULL)

Arguments

Value

Character vector of detected package names, excluding base R packages (for R) or the Python standard library (for Python).

Examples

# Detect the packages a bundled example app uses
app_dependencies(example_app("r"))

Inspect an app directory for Shiny entrypoints

Description

Returns a named list of logical flags for each entrypoint file. Used by the detector and by structure validators to avoid duplicating fs::file_exists calls.

Usage

app_entrypoints(appdir)

Arguments

Value

Named list with elements app_py, app_r, server_r, ui_r.

Refuse to overwrite a protected directory

Description

Aborts with an informative error when dir resolves to a well-known system path (~, /, R.home()) or a path whose absolute form is three characters or fewer (covers drive roots such as ⁠C:\⁠ on Windows).

Usage

assert_safe_to_overwrite(dir)

Arguments

Value

Invisible TRUE when the path is safe.

List Available Examples

Description

Shows all bundled example applications with their descriptions.

Usage

available_examples()

Value

A data frame with columns: name (character ID), language ("r" or "python"), type (app type, "r-shiny" or "py-shiny"), and description (human-readable summary).

Examples

available_examples()

Append app-specific package installs to the Dockerfile

Description

Bakes system dependencies (via the Posit Package Manager sysreqs API and config$dependencies$system_packages) and R/Python package installs into the image at build time so container launch does not have to compile/install packages on the user's machine.

Usage

bake_dockerfile_dependencies(output_dir, dockerfile_dest, config = NULL)

Details

For R apps the base image is rocker/r-ver, which pre-wires P3M binaries; packages are therefore installed via install.packages().

Build Electron Application

Description

Builds a distributable Electron application from a converted Shiny app. Creates platform-specific installers and executables.

Usage

build_electron_app(
  app_dir,
  output_dir,
  app_name = NULL,
  app_type = "r-shiny",
  runtime_strategy = "shinylive",
  sign = FALSE,
  platform = NULL,
  arch = NULL,
  icon = NULL,
  config = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Character string. Path to the built Electron application directory.

Details

This function creates a complete Electron application by:

• Setting up the Electron project structure

• Copying application files and templates

• Installing npm dependencies

• Building platform-specific distributables

Examples

# Build Electron app for current platform
build_electron_app(
  app_dir = "path/to/shinylive/app",
  output_dir = "path/to/electron/build",
  app_name = "My Shiny App",
  app_type = "r-shiny"
)

# Build for multiple platforms
build_electron_app(
  app_dir = "path/to/app",
  output_dir = "path/to/build",
  app_name = "My App",
  app_type = "r-shiny",
  platform = c("win", "mac", "linux")
)

Build for target platforms

Description

Build for target platforms

Usage

build_for_platforms(output_dir, platform, arch, sign = FALSE, verbose = TRUE)

Arguments

Build multi-app Electron application

Description

Build multi-app Electron application

Usage

build_multi_app(
  apps_dir,
  output_dir,
  app_name,
  apps_manifest,
  default_type,
  runtime_strategy,
  sign,
  platform,
  arch,
  icon,
  config,
  overwrite,
  verbose,
  r_packages = NULL,
  r_repos = NULL,
  py_packages = NULL,
  py_index_urls = NULL,
  shinylive_site_dir = NULL
)

Clear the asset cache

Description

Removes cached R installations and/or npm packages from the cache directory.

Usage

cache_clear(what = c("all", "r", "npm", "nodejs", "python"))

Arguments

Value

Invisibly returns NULL.

Details

Use this function to free disk space or force re-downloading of assets:

• "r": Removes only cached R installations

• "npm": Removes only cached npm packages

• "nodejs": Removes only cached Node.js installations

• "python": Removes only cached Python installations

• "all": Removes all cached assets

If the cache directory doesn't exist, a message is shown and nothing is done.

Examples

# Clear everything in the cache
cache_clear()

# Clear only R installations
cache_clear("r")

# Clear only npm packages
cache_clear("npm")

# Clear only Node.js installations
cache_clear("nodejs")

# Clear only Python installations
cache_clear("python")

Get or create the cache directory path

Description

Returns the path where shinyelectron stores downloaded runtimes (R, Python, Node.js) and other cached assets. By default, the directory is created if it doesn't already exist. Pass create = FALSE to query the path without side effects.

Usage

cache_dir(create = TRUE)

Arguments

Value

Character string. Absolute path to the cache directory, typically ⁠~/.cache/shinyelectron/assets⁠ on Linux, ⁠~/Library/Caches/shinyelectron/assets⁠ on macOS, or ⁠\%LOCALAPPDATA\%/shinyelectron/shinyelectron/Cache/assets⁠ on Windows.

Cache Layout

Cached runtimes are organized by type, platform, architecture, and version:

assets/
|-- r/
|   |-- win/x64/4.5.3/
|   |-- mac/arm64/4.5.3/
|-- python/
|   |-- win/x64/3.14.6/
|   |-- mac/arm64/3.14.6/
|-- nodejs/
|   |-- v22.11.0/darwin-arm64/
|   |-- v22.11.0/win-x64/

Use cache_info() to see what's actually installed with disk usage.

See Also

cache_info() to see what's cached, cache_clear() to remove cached assets, cache_remove() to remove a specific version.

Examples

# Query the cache path without creating it
cache_dir(create = FALSE)

# Get or create the cache directory (writes to the user cache dir)
if (interactive()) {
  cache_dir()
}

Show cached runtime information

Description

Lists all cached runtimes (R, Python, Node.js) with their versions, platforms, architectures, and disk usage. Modeled after shinylive::assets_info().

Usage

cache_info(quiet = FALSE)

Arguments

Value

A data frame (returned invisibly) with columns: runtime (character), version (character), platform (character), arch (character), size (character, human-readable), and path (character).

See Also

cache_clear() to remove cached assets, cache_dir() for the cache location.

Examples

# Programmatic access (safe to run -- just inspects the cache dir)
df <- cache_info(quiet = TRUE)
nrow(df)  # number of cached runtimes

# Pretty-print the cache contents
cache_info()

Get path to cached R installation

Description

Creates the path to a specific R installation in the cache based on version, platform, and architecture.

Usage

cache_r_path(version, platform, arch)

Arguments

Value

Character string. The path to the cached R installation for the specified version, platform, and architecture.

Details

The path is structured as ⁠cache_dir()/r/[platform]/[arch]/[version]⁠. This function does not check if the installation exists at that location.

Remove a specific cached runtime version

Description

Removes a single cached runtime version instead of clearing the entire cache. Use cache_info() to see what's available.

Usage

cache_remove(runtime, version, platform = NULL, arch = NULL)

Arguments

Value

Invisibly returns TRUE if removed, FALSE if not found.

See Also

cache_info() to list cached versions, cache_clear() to remove all cached assets of a type.

Examples

# Remove a specific R version
cache_remove("r", "4.4.0", "mac", "arm64")

# Remove a cached Python version
cache_remove("python", "3.14.6", "win", "x64")

# Remove one platform/arch slot of a Node.js version
cache_remove("nodejs", "v22.11.0", "mac", "arm64")

Check Auto-Update Status

Description

Reports the current auto-update configuration status.

Usage

check_auto_update_status(appdir)

Arguments

Value

Invisibly returns the updates configuration list, which is always present because read_config() deep-merges defaults. Elements include enabled (logical, FALSE by default when auto-updates have never been enabled), provider (character), check_on_startup, auto_download, auto_install (logical), and, for the GitHub provider, github (a list with owner, repo, private).

Examples

# Check update configuration on a temporary app
app <- file.path(tempdir(), "check-updates-demo")
dir.create(app, showWarnings = FALSE)
writeLines("library(shiny)", file.path(app, "app.R"))
enable_auto_updates(app, owner = "myusername", repo = "myapp", verbose = FALSE)
check_auto_update_status(app)

Compute SHA256 checksum

Description

Uses tools::sha256sum() to compute SHA256 hash.

Usage

compute_sha256(file_path)

Arguments

Value

Character SHA256 hash, or NULL if unable to compute

Convert a Shiny app to the shinylive format

Description

Dispatches to the R or Python shinylive converter based on language.

Usage

convert_app_to_shinylive(appdir, destdir, app_type, verbose = TRUE)

Arguments

Value

Character. Path to the converted shinylive app.

Convert Python Shiny Application to Shinylive

Description

Converts a Python Shiny application directory into a shinylive application that can run entirely in the browser using Pyodide.

Usage

convert_py_to_shinylive(
  appdir,
  output_dir,
  subdir = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Character string. Path to the converted shinylive application directory.

Details

This function converts a Python Shiny application to shinylive format using the Python shinylive package. The application will run entirely in the browser using Pyodide (Python compiled to WebAssembly).

Requirements:

• Python 3 must be available on the build machine

• The Python shinylive package must be installed (⁠pip install shinylive⁠)

• The app directory must contain an app.py file

Examples

convert_py_to_shinylive(
  appdir = "path/to/python/shiny/app",
  output_dir = "path/to/shinylive/output"
)

Convert Shiny Application to Shinylive

Description

Converts a regular Shiny application directory into a shinylive application that can run entirely in the browser without requiring an R server.

Usage

convert_shiny_to_shinylive(
  appdir,
  output_dir,
  subdir = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Character string. Path to the converted shinylive application directory.

Details

This function converts a Shiny application to shinylive format, which allows the application to run entirely in the browser using WebR. The conversion process:

• Validates the input Shiny application structure

• Converts R code to be compatible with WebR

• Creates necessary shinylive configuration files

• Packages the application for browser execution

Examples

# Convert a Shiny app to shinylive
convert_shiny_to_shinylive(
  appdir = "path/to/shiny/app",
  output_dir = "path/to/shinylive/output"
)

Copy the Dockerfile for the container strategy and bake in app dependencies

Description

Copy the Dockerfile for the container strategy and bake in app dependencies

Usage

copy_and_bake_dockerfiles(output_dir, app_type, config = NULL, verbose = TRUE)

Arguments

Copy application files to Electron project

Description

Copy application files to Electron project

Usage

copy_app_files(
  app_dir,
  output_dir,
  app_type,
  runtime_strategy = NULL,
  verbose = TRUE
)

Arguments

Copy backend module(s) and their shared JS helpers into the build

Description

Copy backend module(s) and their shared JS helpers into the build

Usage

copy_backend_modules(output_dir, backend_module, is_multi_app)

Copy branding assets (icon, splash image, tray icon) into the build

Description

Copy branding assets (icon, splash image, tray icon) into the build

Usage

copy_brand_assets(output_dir, icon, config)

Copy the top-level contents of one directory into another

Description

fs::dir_copy(src, dst) has different semantics across platforms and fs versions: on some it creates dst and copies the contents of src into it, on others it creates dst/basename(src)/.... This helper forces the "copy contents into target" semantics by creating a fresh, empty dst and then copying each top-level entry from src into it with base R.

Usage

copy_dir_contents(src, dst)

Arguments

Value

Invisible dst.

Get default configuration values

Description

Returns the default configuration used when no config file exists or for values not specified in the config file.

Usage

default_config()

Value

List of default configuration values

Valid demo build matrix

Description

Enumerates every (demo, strategy, platform, arch) combination the demo build workflow produces, after applying validity rules. The CI workflow and the download tables in the README and the download-demos article all read this, so the build matrix and the published links cannot drift.

Usage

demo_release_matrix()

Value

A data frame with one row per valid combination and columns demo, name, language, strategy, platform, arch, runner, asset_name, requirement.

Autodetect the app type from a directory

Description

Scans appdir for Shiny entrypoints and returns the implied language. R apps may use app.R or the pair server.R plus ui.R. Python apps use app.py. A directory that carries both R and Python entrypoints is rejected; the multi-app-suite path is the right place to combine them.

Usage

detect_app_type(appdir)

Arguments

Value

Character, either "r-shiny" or "py-shiny".

Detect available container engine

Description

Searches for Docker or Podman on the system.

Usage

detect_container_engine(preference = NULL)

Arguments

Value

Character string ("docker" or "podman") or NULL if none found.

Detect current architecture

Description

Detect current architecture

Usage

detect_current_arch()

Value

Character string representing current architecture ("x64" or "arm64")

Detect current platform

Description

Detect current platform

Usage

detect_current_platform()

Value

Character string representing current platform ("win", "mac", or "linux")

Detect Python package dependencies from requirements files

Description

Reads requirements.txt or pyproject.toml to determine Python package dependencies. Does NOT parse import statements – the module-name-to-package-name mapping (e.g., ⁠import cv2⁠ maps to opencv-python) makes import parsing unreliable.

Usage

detect_py_dependencies(appdir)

Arguments

Details

Prefers requirements.txt over pyproject.toml when both exist. Warns if neither file is found.

Value

Character vector of unique package names (sorted).

Detect R package dependencies from source files

Description

Uses renv::dependencies() to scan R source files for package references. This catches library(), require(), pkg::func(), loadNamespace(), and other patterns.

Usage

detect_r_dependencies(appdir)

Arguments

Value

Character vector of unique package names (sorted), excluding base and recommended R packages.

Disable Auto-Updates

Description

Disables automatic update checking in the configuration file.

Usage

disable_auto_updates(appdir, verbose = TRUE)

Arguments

Value

Invisibly returns the path to the updated config file.

Examples

# Disable updates on a temporary app
app <- file.path(tempdir(), "disable-updates-demo")
dir.create(app, showWarnings = FALSE)
writeLines("library(shiny)", file.path(app, "app.R"))
enable_auto_updates(app, owner = "myusername", repo = "myapp", verbose = FALSE)
disable_auto_updates(app)

Check whether electron-builder produced output for a platform

Description

electron-builder 26.x has a known bug where the build completes and the installer is written to disk, but the process then exits with status 1 during post-build publish metadata. When that happens, processx-invoked npm inherits the non-zero exit even though the .dmg/.exe/.AppImage is sitting right there. We treat "artifact exists" as success.

Usage

dist_has_platform_artifact(output_dir, p)

Arguments

Value

Logical: TRUE if a platform-specific installer is present.

Download and extract a portable runtime into a cache directory

Description

Shared helper for install_r_portable() and install_python_standalone(). Handles the common flow: cache-hit short-circuit, download to temp file, extract by archive type, verify the expected executable appears, cleanup.

Usage

download_and_extract_portable_tool(
  label,
  version,
  install_path,
  download_url,
  executable_finder,
  force = FALSE,
  is_installed = FALSE,
  expected_sha256 = NULL,
  verbose = TRUE
)

Arguments

Details

install_nodejs() has additional requirements (SHA256 checksums, directory renaming after extraction) and implements its own flow.

Value

Invisibly returns the installation path.

Fetch the latest published Electron version from the npm registry

Description

Queries ⁠https://registry.npmjs.org/electron/latest⁠ and returns the version field as a character string. Used when dependencies$electron$version is set to "latest".

Usage

electron_latest_version()

Value

Character version string (e.g. "41.0.0").

Embed a portable Python runtime into a bundled Electron build

Description

Behavior-preserving extraction of the Python bundled-embedding block from build_electron_app(). ALWAYS installs + copies the interpreter so the shared runtime/Python path exists for suite-wide bundled detection; only the pip install is gated on a non-empty packages set. Warn-only (not abort) on pip failure; the result is not verified, matching the original block. Reproduces the three output_dir-derived paths and the unix-only fallback glob so the native-py.js sys.path expectations hold.

Usage

embed_python_runtime(
  output_dir,
  packages,
  index_urls,
  version,
  platform,
  arch,
  verbose = TRUE
)

Arguments

Value

Invisibly, the path to the embedded runtime/Python directory.

Embed a portable R runtime into a bundled Electron build

Description

Behavior-preserving extraction of the R bundled-embedding block from build_electron_app(). ALWAYS installs + copies the interpreter (and resolves symlinks) so the shared runtime/R path exists for suite-wide bundled detection; only the package install is gated on a non-empty packages set. packages is the DIRECT set (as stored in dependencies.json); the recursive dependency closure and the pre_installed setdiff are resolved here, against the freshly-created runtime/R/library.

Usage

embed_r_runtime(
  output_dir,
  packages,
  repos,
  version,
  platform,
  arch,
  verbose = TRUE
)

Arguments

Value

Invisibly, the path to the embedded runtime/R directory.

Enable Auto-Updates

Description

Configures automatic update checking for your Electron application. GitHub Releases is the only provider supported today. S3 and Generic HTTP providers are planned and will be added in a future release.

Usage

enable_auto_updates(
  appdir,
  provider = "github",
  owner = NULL,
  repo = NULL,
  check_on_startup = TRUE,
  auto_download = FALSE,
  auto_install = FALSE,
  verbose = TRUE
)

Arguments

Details

Auto-updates require:

1. A published application (e.g., to GitHub Releases)

2. Proper code signing for macOS and Windows (recommended)

3. The electron-updater package (automatically included in build)

Update Providers

GitHub Releases (recommended for open source):

• Automatically detects new releases by comparing semver tags

• Requires owner and repo parameters

• Private repos require GH_TOKEN environment variable

S3 Bucket (planned, not yet supported):

• For self-hosted updates behind a CDN

• Configure bucket, region, and path in ⁠_shinyelectron.yml⁠

• Bucket must allow public reads or use CloudFront signed URLs

• Required bucket structure: ⁠/{path}/latest-mac.yml⁠, latest-linux.yml, latest.yml

• Note: enable_auto_updates() currently rejects "s3" as a provider; S3 support will be added in a future release.

Generic HTTP Server (planned, not yet supported):

• For any HTTP server hosting update files

• Configure base URL in ⁠_shinyelectron.yml⁠

• Server must host latest-mac.yml, latest-linux.yml, latest.yml at the URL root

• Note: enable_auto_updates() currently rejects "generic" as a provider; Generic HTTP support will be added in a future release.

Publishing Updates (GitHub Releases)

After enabling auto-updates, follow this workflow to publish updates:

1. Bump version in ⁠_shinyelectron.yml⁠ (e.g., version: "1.1.0")

2. Rebuild with export(appdir, destdir, build = TRUE)

3. Create a GitHub Release with a semver tag matching the version:

   • Tag: v1.1.0 (the v prefix is required)

   • Upload the built artifacts from ⁠destdir/electron-app/dist/⁠:

     • macOS: .dmg and latest-mac.yml

     • Windows: .exe installer and latest.yml

     • Linux: .AppImage and latest-linux.yml

4. The app checks for updates on startup (if check_on_startup = TRUE) and notifies the user when a new version is available

Code Signing Requirement

macOS and Windows require code-signed builds for auto-updates to work. Unsigned apps will fail the update verification step. Set signing: sign: true in your config and provide credentials via environment variables (see ?validate_signing_config).

Value

Invisibly returns the path to the updated config file.

See Also

init_config() for creating initial configuration

Examples

# Enable GitHub-based updates on a temporary app
app <- file.path(tempdir(), "enable-updates-demo")
dir.create(app, showWarnings = FALSE)
writeLines("library(shiny)", file.path(app, "app.R"))
enable_auto_updates(app, owner = "myusername", repo = "myapp")

# Enable with automatic download
enable_auto_updates(app, owner = "myorg", repo = "dashboard",
                    auto_download = TRUE)

Get Path to an Example Application

Description

Returns the path to a bundled example application directory. Use this path as the appdir argument to export().

Usage

example_app(name)

Arguments

Value

Character string. Path to the example app directory.

Examples

# Get the path to a bundled example
example_app("r")
example_app("python")

if (interactive()) {
  # Pass the path to export() to build a desktop app
  path <- example_app("r")
  export(path, "output", app_type = "r-shiny", runtime_strategy = "system")
}

Export Shiny Application as Electron Desktop Application

Description

Main entry point function that wraps the conversion, building, and optionally running of a Shiny application as an Electron desktop application.

Usage

export(
  appdir,
  destdir,
  app_name = NULL,
  app_type = NULL,
  runtime_strategy = NULL,
  sign = FALSE,
  platform = NULL,
  arch = NULL,
  icon = NULL,
  overwrite = FALSE,
  build = TRUE,
  run_after = FALSE,
  open_after = FALSE,
  verbose = TRUE
)

Arguments

Value

List containing paths to the converted app and built Electron app (if built).

Details

This is the main function of the package that orchestrates the entire process:

• Validates the input Shiny application

• Converts the Shiny app to the specified format (shinylive by default)

• Sets up the Electron project structure

• Optionally builds distributable packages

• Optionally runs the application for testing

Supported Combinations

Two languages, five delivery strategies.

• r-shiny or py-shiny plus runtime_strategy = "shinylive": app compiles to WebAssembly and runs inside the Electron window with no runtime on disk.

• r-shiny or py-shiny plus "auto-download", "bundled", "system", or "container": app runs against a real R or Python process supplied by the chosen strategy.

Examples

# Simplest call: app_type autodetects, runtime_strategy defaults to shinylive
export(
  appdir = "path/to/shiny/app",
  destdir = "path/to/electron/output"
)

# Run against a real R process instead of shinylive
export(
  appdir = "path/to/shiny/app",
  destdir = "path/to/output",
  runtime_strategy = "bundled"
)

# Pin language explicitly when autodetection is ambiguous
export(
  appdir = "path/to/shiny/app",
  destdir = "path/to/output",
  app_type = "r-shiny",
  runtime_strategy = "system"
)

Export multi-app Shiny suite as Electron application

Description

Export multi-app Shiny suite as Electron application

Usage

export_multi_app(
  appdir,
  destdir,
  config,
  app_name = NULL,
  runtime_strategy = NULL,
  sign = FALSE,
  platform = NULL,
  arch = NULL,
  icon = NULL,
  overwrite = FALSE,
  build = TRUE,
  run_after = FALSE,
  open_after = FALSE,
  verbose = TRUE
)

Installer extension for a platform

Description

The shinyelectron electron-builder template targets dmg on macOS, nsis (an .exe) on Windows, and AppImage on Linux.

Usage

ext_for(platform)

Arguments

Value

Character vector of file extensions.

Select the tar program used to unpack a .tar.gz runtime archive

Description

Windows ships bsdtar (libarchive) at ⁠System32\\tar.exe⁠. It handles the PAX / long-name records in python-build-standalone archives that R's internal tar cannot (those surface as "embedded nul in string" errors), and unlike a GNU tar from Git for Windows it does not misparse ⁠C:\\...⁠ paths as remote hosts. Fall back to R's internal tar only when bsdtar is unavailable. On macOS / Linux the system tar (bsdtar or GNU tar) already handles PAX records, including the Apple com.apple.cs.CodeSignature xattrs in portable R archives.

Usage

extract_tar_program(
  os_type = .Platform$OS.type,
  system_root = Sys.getenv("SystemRoot", unset = "C:\\Windows")
)

Arguments

Value

A value suitable for the tar argument of utils::untar(): a path to a tar executable, the string "internal", or the result of Sys.which().

Fetch a published SHA-256 checksum for a portable runtime archive

Description

Reads a checksum file published alongside a runtime release and returns the hash for one archive. Two layouts are supported, both in the standard sha256sum format (⁠<hash> <filename>⁠):

Usage

fetch_published_sha256(checksum_url, asset_filename = NULL)

Arguments

Details

• Per-asset sidecar (portable R): the checksum file contains a single line for the archive. Pass asset_filename = NULL and the first line's hash is returned.

• Combined SHA256SUMS (python-build-standalone): the file lists every asset. Pass asset_filename and the matching line's hash is returned.

Returns NULL when the checksum cannot be fetched or no matching entry is found, so callers can continue without verification rather than failing on a transient network error (the same graceful-skip behavior as the Node.js installer).

Value

Character SHA-256 hash, or NULL.

Locate Rscript inside a bundled portable-R runtime directory

Description

The portable-r distribution extracts to a subdirectory named ⁠portable-r-<version>-<os>-<arch>/⁠. Rscript lives at ⁠<subdir>/bin/Rscript[.exe]⁠. Searches for that layout first, then falls back to a flat layout in case a future portable build drops the subdir.

Usage

find_bundled_rscript(runtime_dir)

Arguments

Value

Character path to Rscript, or NULL if not found.

Find configuration file

Description

Searches for _shinyelectron.yml in the given directory.

Usage

find_config(appdir)

Arguments

Value

Character path to config file, or NULL if not found

Find the Python command

Description

Searches for python3 first (Unix) or python first (Windows) on the system PATH and verifies it actually runs (Windows Store aliases exist but fail).

Usage

find_python_command()

Value

Character string or NULL. The Python command name, or NULL if not found.

Format directory size as human-readable string

Description

Format directory size as human-readable string

Usage

format_dir_size(path)

Arguments

Value

Character string like "142 MB".

Build the container backend configuration

Description

Produces the container-specific settings that are merged into backend_config (see generate_template_variables()) and consumed by inst/electron/backends/container.js at runtime. The configured engine is passed through as-is; image selection and engine auto-detection happen on the end user's machine in container.js.

Usage

generate_container_config(config, app_type = NULL)

Arguments

Value

Named list of container settings.

Generate a dependency manifest file

Description

Creates a JSON manifest describing the packages an app needs. This manifest is written into the Electron app and used by the auto-download and container strategies to install packages at runtime.

Usage

generate_dependency_manifest(
  packages,
  language,
  repos = NULL,
  index_urls = NULL
)

Arguments

Value

Character string of JSON content.

Generate package.json content for Electron app

Description

Programmatically creates the package.json content based on the backend type and configuration. This replaces the previous Whisker template approach to avoid fragile JSON + Mustache comma handling.

Usage

generate_package_json(
  app_slug,
  app_version,
  backend,
  config,
  has_icon = FALSE,
  sign = FALSE,
  is_multi_app = FALSE
)

Arguments

Value

Character string. The JSON content for package.json.

Generate a Python runtime manifest for auto-download

Description

Generate a Python runtime manifest for auto-download

Usage

generate_python_runtime_manifest(
  version,
  platform = NULL,
  arch = NULL,
  release_date = NULL
)

Arguments

Value

Character string. JSON content.

Generate a runtime manifest for auto-download

Description

Creates a JSON manifest that the Electron app reads on first launch to download the R runtime.

Usage

generate_runtime_manifest(version, platform = NULL, arch = NULL)

Arguments

Value

Character string. JSON content.

Build the Whisker template variable list for the shared shell

Description

Constructs the named list passed to whisker::whisker.render() when assembling the Electron app. Kept separate from process_templates() so the variable construction is testable independently.

Usage

generate_template_variables(
  app_name,
  app_slug,
  app_type,
  runtime_strategy,
  icon,
  backend_module,
  brand,
  config,
  is_multi_app = FALSE,
  apps_manifest = NULL
)

Arguments

Details

Most variables here correspond to a {{...}} placeholder in inst/electron/shared/main.js, lifecycle.html, or launcher.html. The list is a superset: some entries are serialized into backend_config_json (and consumed by the backend modules rather than a template) or are reserved for future placeholders. Adding a new placeholder requires adding it here.

Value

Named list suitable for Whisker rendering.

Get Node.js command

Description

Returns the path to the Node.js executable, preferring locally installed versions managed by shinyelectron.

Usage

get_node_command(prefer_local = TRUE)

Arguments

Value

Character string path to node executable

Get npm command

Description

Returns the path to the npm executable, preferring locally installed versions managed by shinyelectron.

Usage

get_npm_command(prefer_local = TRUE)

Arguments

Value

Character string path to npm executable

Initialize configuration file

Description

Creates a template _shinyelectron.yml file in the specified directory.

Usage

init_config(appdir, app_name = NULL, overwrite = FALSE, verbose = TRUE)

Arguments

Value

Invisibly returns the path to the created config file.

See Also

wizard() for an interactive configuration generator; show_config() to display the merged effective configuration.

Examples

# Create a config for a temporary app
app <- file.path(tempdir(), "init-config-demo")
dir.create(app, showWarnings = FALSE)
writeLines("library(shiny)", file.path(app, "app.R"))
init_config(app, app_name = "My App")

Install Node.js locally

Description

Downloads and installs Node.js to the shinyelectron cache directory. This allows using Node.js/npm without requiring system-wide installation.

Usage

install_nodejs(
  version = NULL,
  platform = NULL,
  arch = NULL,
  force = FALSE,
  verbose = TRUE
)

Arguments

Value

Invisibly returns the path to the installed Node.js directory.

See Also

install_r_portable(), install_python_standalone() for other runtime installers.

Examples

# Install latest LTS version
install_nodejs()

# Install specific version
install_nodejs(version = "20.0.0")

# Force reinstall
install_nodejs(force = TRUE)

Install npm dependencies

Description

Install npm dependencies

Usage

install_npm_dependencies(output_dir, verbose = TRUE)

Arguments

Install a portable Python distribution

Description

Downloads and caches a portable Python build from python-build-standalone.

Usage

install_python_standalone(
  version = NULL,
  platform = NULL,
  arch = NULL,
  force = FALSE,
  verbose = TRUE
)

Arguments

Value

Character string. Path to the installed Python directory.

See Also

install_r_portable(), install_nodejs() for other runtime installers; python_executable() to find the installed Python path.

Examples

# Install default Python version
install_python_standalone()

# Install specific version
install_python_standalone(version = "3.12.0")

Install a portable R distribution

Description

Downloads and caches a portable R build. Follows the same pattern as install_nodejs().

Usage

install_r_portable(
  version = NULL,
  platform = NULL,
  arch = NULL,
  force = FALSE,
  verbose = TRUE
)

Arguments

Value

Character string. Path to the installed R directory.

See Also

install_python_standalone(), install_nodejs() for other runtime installers; r_executable() to find the installed Rscript path.

Examples

# Install latest R release
install_r_portable()

# Install specific version for a target platform
install_r_portable(version = "4.4.0", platform = "win", arch = "x64")

Check if config is multi-app mode

Description

Check if config is multi-app mode

Usage

is_multi_app(config)

Arguments

Value

Logical.

Manifest Schemas (R to JS Contract)

Description

shinyelectron generates three JSON manifest files at build time that the Electron runtime reads on the end user's machine. These are the de-facto API contract between R and JavaScript.

Details

Each manifest carries a schema_version field (the MANIFEST_SCHEMA_VERSION constant in R, mirrored in inst/electron/backends/utils.js). The JS side warns on mismatch rather than crashing, so older apps can keep running after a schema bump.

dependencies.json

Generated by generate_dependency_manifest(). Consumed by inst/electron/backends/dependency-checker.js. Describes the packages an app needs at runtime.

{
  "schema_version": "2",
  "language": "r" | "python",
  "packages": ["shiny", "bslib", ...],
  "binary_only": true,
  "repos": ["https://cloud.r-project.org"],       // R only
  "index_urls": ["https://pypi.org/simple"],      // Python only
  "system_deps": {                                 // optional, R only
    "debian": ["libcurl4-openssl-dev", ...],
    "fedora": ["libcurl-devel", ...]
  }
}

runtime-manifest.json

Generated by generate_runtime_manifest() (R) and generate_python_runtime_manifest() (Python). Consumed by inst/electron/backends/runtime-downloader.js. Tells the auto-download strategy where to fetch the runtime.

{
  "schema_version": "2",
  "language": "r" | "python",
  "version": "4.5.3",
  "download_url": "https://...",
  "install_path": "~/.shinyelectron/runtimes/R-4.5.3",
  "platform": "win" | "mac" | "linux",
  "arch": "x64" | "arm64",
  "sha256": "..."                                  // optional
}

apps-manifest.json

Generated by export_multi_app(). Consumed by inst/electron/shared/main.js. Drives the multi-app launcher UI.

{
  "schema_version": "2",
  "default_type": "r-shiny",
  "runtime_strategy": "auto-download",
  "apps": [
    {
      "id": "dashboard",
      "name": "Dashboard",
      "description": "...",
      "type": "r-shiny",
      "runtime_strategy": "auto-download",
      "icon": null,
      "serve": { "kind": "native", "path": "src/apps/dashboard", "runtime_strategy": "auto-download" }
    },
    {
      "id": "viewer",
      "name": "Viewer",
      "description": "...",
      "type": "r-shiny",
      "runtime_strategy": "shinylive",
      "icon": null,
      "serve": { "kind": "shinylive", "site": "src/shinylive-site", "subdir": "viewer" }
    },
    {
      "id": "boxed",
      "name": "Boxed",
      "description": "...",
      "type": "r-shiny",
      "runtime_strategy": "container",
      "icon": null,
      "serve": { "kind": "container", "path": "src/apps/boxed" }
    }
  ]
}

Deep merge two lists

Description

Recursively merges config into defaults, where config values override defaults.

Usage

merge_config_deep(defaults, config)

Arguments

Value

Merged list

Merge detected Python dependencies with config declarations

Description

Merge detected Python dependencies with config declarations

Usage

merge_py_dependencies(detected, config_deps)

Arguments

Value

List with packages (character vector) and index_urls (list).

Merge detected R dependencies with config declarations

Description

Combines auto-detected packages with user-declared packages from config. When auto_detect is FALSE, only declared packages are used.

Usage

merge_r_dependencies(detected, config_deps)

Arguments

Value

List with packages (character vector) and repos (list).

Initialize a sitrep results list with the standard shape

Description

Each sitrep function accumulates issues and recommendations as it runs. This helper ensures all sitrep results expose the same two fields so the top-level sitrep_shinyelectron() aggregator can iterate over them uniformly.

Usage

new_sitrep_results(extra = list())

Arguments

Value

List with issues and recommendations character vectors plus any extras.

Download Node.js checksums

Description

Download Node.js checksums

Usage

nodejs_download_checksums(version)

Arguments

Value

Named character vector (filename = checksum)

Generate Node.js download URL

Description

Generate Node.js download URL

Usage

nodejs_download_url(version, platform, arch)

Arguments

Value

Character URL to download Node.js

Get path to local Node.js executable

Description

Get path to local Node.js executable

Usage

nodejs_executable(version = NULL, platform = NULL, arch = NULL)

Arguments

Value

Character path to node executable, or NULL if not found

Get Node.js installation path in cache

Description

Get Node.js installation path in cache

Usage

nodejs_install_path(version = NULL, platform = NULL, arch = NULL)

Arguments

Value

Character path to Node.js installation

Check if Node.js is installed locally

Description

Check if Node.js is installed locally

Usage

nodejs_is_installed(version = NULL)

Arguments

Value

Logical TRUE if installed

Get latest Node.js LTS version

Description

Queries the Node.js distribution API to find the latest LTS version.

Usage

nodejs_latest_lts()

Value

Character string with version number (without 'v' prefix)

List installed Node.js versions

Description

List installed Node.js versions

Usage

nodejs_list_installed()

Value

Character vector of installed versions (sorted newest first)

Get Node.js SHASUMS URL

Description

Get Node.js SHASUMS URL

Usage

nodejs_shasums_url(version)

Arguments

Value

Character URL to SHASUMS256.txt

Environment for Node.js and npm child processes

Description

npm can be launched by its absolute path, but package lifecycle scripts invoke node by name. When shinyelectron manages a Node.js install that is not already on PATH, this makes that directory discoverable to npm and every process it starts.

Usage

nodejs_subprocess_env()

Details

The result uses processx's special "current" entry so the child inherits the full parent environment with PATH extended, rather than replacing it. Replacing it would drop variables that npm and electron-builder depend on (for example APPDATA and LOCALAPPDATA on Windows, or HOME elsewhere).

Value

A character vector for the env argument of processx::run() and run_command_safe(), or NULL when Node.js is already on PATH or cannot be resolved (the inherited environment is then used unchanged).

Verify file checksum

Description

Verify file checksum

Usage

nodejs_verify_checksum(file_path, expected_checksum)

Arguments

Value

Logical TRUE if valid (or if verification unavailable)

Normalize app_type and runtime_strategy arguments

Description

Translates legacy app_type values (r-shinylive, py-shinylive) to the canonical language pair (r-shiny, py-shiny) and backfills runtime_strategy = "shinylive" when the caller has not set it. Emits a deprecation warning of class "shinyelectron_deprecated_app_type" so callers can muffle it and tests can match it precisely. Errors when a legacy type is combined with an explicit non-shinylive strategy, since that combination never worked under the old API.

Usage

normalize_app_type_arg(app_type, runtime_strategy = NULL)

Arguments

Value

List with elements app_type (canonical or NULL), runtime_strategy (may still be NULL), and deprecated (logical).

Get path to local npm executable

Description

Get path to local npm executable

Usage

npm_executable(version = NULL, platform = NULL, arch = NULL)

Arguments

Value

Character path to npm executable, or NULL if not found

Parse pyproject.toml dependencies section

Description

Simple parser for the ⁠[project] dependencies⁠ array in pyproject.toml. Does not handle complex TOML – just extracts quoted dependency strings.

Usage

parse_pyproject_toml(path)

Arguments

Value

Character vector of package names.

Parse requirements.txt file

Description

Parse requirements.txt file

Usage

parse_requirements_txt(path)

Arguments

Value

Character vector of package names.

Fetch the latest python-build-standalone release from GitHub

Description

Queries the single releases/latest endpoint. This is a small, reliable call, unlike the full release list which is large enough to time out (HTTP 504) on this repository. The latest release carries the newest patch of every currently supported CPython minor, so it resolves "latest" and any current version on its own. A thin network wrapper so tests can stub it.

Usage

pbs_latest_release()

Value

A single release object with a tag_name field and an assets list.

List python-build-standalone releases from GitHub

Description

Fetches release metadata from the astral-sh/python-build-standalone GitHub API. Returns a list of release objects, each with a tag_name field and an assets list whose elements have a name field. Releases are ordered newest first (GitHub API default). This function is intentionally a thin network wrapper so it can be stubbed in tests.

Usage

pbs_list_releases()

Value

List of release objects from the GitHub releases API.

Prepare native Shiny app files for packaging

Description

Copies the app source into ⁠destdir/shiny-app/⁠, detects package dependencies, and writes runtime + dependency manifests that the Electron backends will consume at launch time.

Usage

prepare_native_app_files(
  appdir,
  destdir,
  app_type,
  runtime_strategy,
  platform,
  arch,
  config,
  verbose = TRUE
)

Arguments

Value

List with elements converted_app (path) and dependencies (NULL or the resolved dep info).

Process and copy Electron templates

Description

Orchestrates the Electron project assembly: renders shared Whisker templates, copies the appropriate backend modules, sets up Dockerfiles for container strategy, generates package.json, and copies brand assets. Each step is a focused helper in this file.

Usage

process_templates(
  output_dir,
  app_name,
  app_type,
  runtime_strategy = "shinylive",
  icon = NULL,
  config = NULL,
  sign = FALSE,
  is_multi_app = FALSE,
  apps_manifest = NULL,
  verbose = TRUE
)

Arguments

Construct download URL for portable Python

Description

Uses python-build-standalone releases for portable Python builds.

Usage

python_download_url(version, platform = NULL, arch = NULL, release_date)

Arguments

Value

Character string. Download URL.

Get the path to the Python executable in a cached installation

Description

Get the path to the Python executable in a cached installation

Usage

python_executable(version, platform = NULL, arch = NULL)

Arguments

Value

Character string or NULL.

Published SHA-256 checksum for a portable Python archive

Description

python-build-standalone publishes one SHA256SUMS file per release listing every asset. Returns NULL when unavailable or unmatched so the caller can continue without verification.

Usage

python_expected_sha256(version, platform = NULL, arch = NULL, release_date)

Arguments

Value

Character SHA-256 hash, or NULL.

Get the installation path for a cached Python version

Description

Get the installation path for a cached Python version

Usage

python_install_path(version, platform = NULL, arch = NULL)

Arguments

Value

Character string. Path to the cached Python installation.

Check if a portable Python version is installed

Description

Check if a portable Python version is installed

Usage

python_is_installed(version, platform = NULL, arch = NULL)

Arguments

Value

Logical.

Resolve a Python version to its python-build-standalone release

Description

Scans release asset names of the form ⁠cpython-<ver>+<release>-<arch>-<os>-install_only.tar.gz⁠. For an explicit version, returns the newest release that contains an asset for that version. For "latest", returns the first CPython version found in the newest release.

Usage

python_resolve_pbs(version = "latest")

Arguments

Details

Resolution tries the lightweight releases/latest endpoint first via pbs_latest_release(), which carries the newest patch of every supported minor and resolves the common case in one reliable call. It falls back to the full release history (pbs_list_releases(), which can time out) only when the latest release does not contain the requested version. Network access is isolated to those two helpers so tests can stub them.

Value

Named list with elements version (character) and release (character YYYYMMDD tag).

URL of the python-build-standalone SHA256SUMS file for a release

Description

URL of the python-build-standalone SHA256SUMS file for a release

Usage

python_sha256sums_url(release_date)

Arguments

Value

Character URL.

Environment for spawning Python child processes

Description

R prepends its own and related library directories to LD_LIBRARY_PATH (its lib directory plus system paths such as ⁠/usr/lib/x86_64-linux-gnu⁠). When a Python child inherits that, the dynamic loader can resolve a system libpython ahead of the interpreter's own; the interpreter then computes a different sys.prefix and its site module drops site-packages from sys.path, so pip-installed packages (for example the Python shinylive CLI) become unimportable and the process fails with ⁠No module named ...⁠ even though the package is installed. Python resolves its own libraries via rpath, so LD_LIBRARY_PATH is removed for Python children. A no-op on platforms / installs where it is not set (Windows, macOS, most user setups).

Usage

python_subprocess_env()

Value

A named character vector suitable for the env argument of processx::run().

Query Linux system package names for a set of R packages

Description

Resolves the distribution system packages required by pkgs and their recursive dependencies using the Posit Package Manager system-requirements service. Returns character(0) on any failure so callers degrade gracefully (a user can still name packages via dependencies.system_packages).

Usage

query_sysreqs(pkgs, distribution = "ubuntu", release = "24.04")

Arguments

Details

Queried over HTTP directly rather than through pak::pkg_sysreqs(), whose resolver returns an empty mapping in common configurations even when the underlying data is available.

Value

Character vector of system package names (sorted, de-duplicated).

Construct download URL for portable R

Description

Generates the download URL for an R build from CRAN.

Usage

r_download_url(version, platform = NULL, arch = NULL)

Arguments

Value

Character string. Download URL.

Get the path to the Rscript executable in a cached installation

Description

Get the path to the Rscript executable in a cached installation

Usage

r_executable(version, platform = NULL, arch = NULL)

Arguments

Value

Character string or NULL. Path to Rscript, or NULL if not found.

Published SHA-256 checksum for a portable R archive

Description

Portable R publishes a per-asset .sha256 sidecar next to each release archive (⁠<archive-url>.sha256⁠). Returns NULL when unavailable so the caller can continue without verification.

Usage

r_expected_sha256(version, platform = NULL, arch = NULL)

Arguments

Value

Character SHA-256 hash, or NULL.

Get the installation path for a cached R version

Description

Get the installation path for a cached R version

Usage

r_install_path(version, platform = NULL, arch = NULL)

Arguments

Value

Character string. Path to the cached R installation.

Check if a portable R version is installed

Description

Check if a portable R version is installed

Usage

r_is_installed(version, platform = NULL, arch = NULL)

Arguments

Value

Logical.

Get the latest R release version

Description

Queries the R API for the current release version.

Usage

r_latest_version()

Value

Character string. The latest R version (e.g., "4.4.1").

Get the latest R version available as a portable-r build

Description

The bundled and auto-download strategies download R from the portable-r release repos, which can lag behind the newest R release (so the latest R from r_latest_version() may have no portable build yet, yielding a 404). This returns the latest version that actually exists for the target platform, falling back to r_latest_version() if the release API cannot be reached.

Usage

r_portable_latest_version(platform = NULL)

Arguments

Value

Character string. The latest available portable-r version.

Read _brand.yml file

Description

Reads a _brand.yml file from the app directory for visual customization. Follows the Posit brand.yml specification.

Usage

read_brand_yml(appdir)

Arguments

Value

List with brand settings, or NULL if no file found.

Read configuration file

Description

Reads and parses _shinyelectron.yml from the app directory. If the file doesn't exist, returns default configuration.

Usage

read_config(appdir)

Arguments

Value

List of configuration values (merged with defaults)

Render shared Electron templates (main.js, lifecycle.html, preload.js, launcher.html)

Description

Render shared Electron templates (main.js, lifecycle.html, preload.js, launcher.html)

Usage

render_shared_templates(output_dir, template_vars, is_multi_app)

Resolve application dependencies

Description

Top-level function that detects, merges, and returns the final list of package dependencies for an app. Called from export() for native app types.

Usage

resolve_app_dependencies(appdir, app_type, runtime_strategy, config)

Arguments

Value

List with packages, language, and repos/index_urls, or NULL for the shinylive strategy.

Resolve the runtime strategy for a multi-app entry

Description

Order of precedence: explicit per-app runtime_strategy, then legacy per-app type (forces "shinylive"), then suite-level build.runtime_strategy, then the package default "shinylive".

Usage

resolve_app_strategy(app, config)

Arguments

Value

Character string. The resolved runtime strategy.

Resolve the app type for a multi-app entry

Description

Reads per-app type, falls back to suite-level build.type, and routes legacy values through normalize_app_type_arg() so the caller always sees canonical "r-shiny" / "py-shiny". A legacy per-app type is treated as a self-contained shinylive declaration and does not mix with the suite-level runtime_strategy, since the two could otherwise conflict (e.g. a legacy "r-shinylive" entry inside a suite whose default strategy is "system").

Usage

resolve_app_type(app, config)

Arguments

Value

Character string. The resolved canonical app type.

Determine the backend module filename for an app type and runtime strategy

Description

Determine the backend module filename for an app type and runtime strategy

Usage

resolve_backend_module(app_type, runtime_strategy)

Arguments

Value

Character string. The backend module filename (e.g., "shinylive.js").

Resolve Posit brand.yml palette references

Description

In a brand.yml color block the semantic roles (primary, background, foreground, ...) may either hold a colour directly or name an entry in color.palette. shinyelectron reads these roles verbatim for the Electron shell, so a reference such as primary: plum must be resolved to its palette value before use. Roles that already hold a literal colour are left untouched.

Usage

resolve_brand_palette(brand)

Arguments

Value

The brand list with color roles resolved against color.palette.

Resolve the active _brand.yml for template rendering

Description

Prefers the single-app location (src/app); for multi-app, falls back to the first listed app if the shared location has no brand file.

Usage

resolve_brand_yml(output_dir, is_multi_app, apps_manifest)

Resolve a Python version to its python-build-standalone release (offline-first)

Description

Uses the offline default pin when the version matches it (no network), and only queries the registry for a custom or "latest" version.

Usage

resolve_python_pbs(version)

Arguments

Value

Named list with elements version (character) and release (character YYYYMMDD tag).

Resolve the runtime version to use for a build

Description

Precedence: an explicit ⁠dependencies.<runtime>.version⁠ in config wins; the literal "latest" calls the live resolver; otherwise the maintained pin in SHINYELECTRON_DEFAULTS$runtime_versions is used.

Usage

resolve_runtime_version(runtime, config)

Arguments

Value

Character version string.

Restore environment variables

Description

Restore environment variables

Usage

restore_environment(old_env)

Arguments

Run a command safely and return the result

Description

Wraps processx::run() with consistent error handling. Returns a list with status, stdout, and stderr. Never throws: a command that cannot be started, fails, or times out is reported as a non-zero status, so a diagnostic probe cannot abort the calling session.

Usage

run_command_safe(command, args = character(), timeout = 30, env = NULL)

Arguments

Details

processx is used rather than base::system2() because a modified env is honored on every platform (system2's env is a no-op on Windows for programs like node and python), and arguments are passed as an argv array without shell quoting.

Value

List with status, stdout, stderr.

Run Electron Application for Testing

Description

Launches a previously exported Electron application for testing and debugging without building distributable packages. Pass the electron-app directory from a prior export() call.

Usage

run_electron_app(app_dir, port = 3000, open_devtools = TRUE, verbose = TRUE)

Arguments

Value

Invisibly returns the completed processx::run() result list (with status, stdout, and stderr) after Electron exits, or NULL if the run is interrupted. Note that this call blocks until the Electron window is closed.

Details

This function starts the Electron application for testing, which:

• Opens the application in an Electron window

• Optionally opens Chromium DevTools for debugging

• Does NOT build distributable packages (use export(build = TRUE) for that)

Examples

# Run a previously exported Electron app in development mode
run_electron_app("path/to/electron/app")

# Run with custom port and no dev tools
run_electron_app(
  app_dir = "path/to/app",
  port = 8080,
  open_devtools = FALSE
)

Set development environment variables

Description

Set development environment variables

Usage

set_dev_environment(port, open_devtools)

Arguments

Value

Named list of old environment variables

Setup Electron project structure

Description

Setup Electron project structure

Usage

setup_electron_project(output_dir, app_name, app_type, verbose = TRUE)

Arguments

Show Effective Configuration

Description

Pretty-prints the merged effective configuration (params + config file + defaults) for a shinyelectron app directory. Useful for debugging and verifying settings.

Usage

show_config(appdir = ".")

Arguments

Value

Invisibly returns the merged configuration list.

Examples

# Show the merged configuration for a bundled example app
show_config(example_app("r"))

Build Tools Situation Report

Description

Checks platform-specific build tools required for creating Electron distributables.

Usage

sitrep_electron_build_tools(verbose = TRUE)

Arguments

Value

Invisibly returns a list with build tools information.

Examples

# Check build tools
sitrep_electron_build_tools()

Dependencies Situation Report

Description

Checks R package dependencies required for shinyelectron functionality.

Usage

sitrep_electron_dependencies(verbose = TRUE)

Arguments

Value

Invisibly returns a list with dependency information.

Examples

# Check R package dependencies (quiet = returns a list invisibly)
deps <- sitrep_electron_dependencies(verbose = FALSE)
length(deps$missing_required)


# Pretty-printed report
sitrep_electron_dependencies()

Project Situation Report

Description

Checks if the current directory contains a valid Electron project and diagnoses common project-related issues.

Usage

sitrep_electron_project(project_dir = ".", verbose = TRUE)

Arguments

Value

Invisibly returns a list with project diagnostic information.

Examples

# Check the current directory for a shinyelectron project
sitrep_electron_project()

# Check a specific directory
sitrep_electron_project(tempdir())

System Requirements Situation Report

Description

Checks system requirements for shinyelectron including Node.js, npm, operating system, and architecture.

Usage

sitrep_electron_system(verbose = TRUE)

Arguments

Value

Invisibly returns a list with diagnostic information.

Examples

# Check system requirements
sitrep_electron_system()

# Get diagnostic info without printing
info <- sitrep_electron_system(verbose = FALSE)

Complete Situation Report

Description

Runs all diagnostic checks and provides a comprehensive report of your shinyelectron setup.

Usage

sitrep_shinyelectron(project_dir = ".", verbose = TRUE)

Arguments

Value

Invisibly returns a list with all diagnostic information.

Examples

# Complete diagnostic check of the current setup
sitrep_shinyelectron()

# Get results as a list, without printing
results <- sitrep_shinyelectron(verbose = FALSE)

# Check a specific project directory
sitrep_shinyelectron(tempdir())

Convert a display name to a path-safe slug

Description

Converts an application display name to a lowercase, hyphen-separated string safe for use in file paths, container names, and npm package names.

Usage

slugify(name)

Arguments

Value

Character string. The slugified name.

Validate application name

Description

Validate application name

Usage

validate_app_name(app_name)

Arguments

Validate application type

Description

Validate application type

Usage

validate_app_type(app_type)

Arguments

Validate target architecture

Description

Validate target architecture

Usage

validate_arch(arch)

Arguments

Validate build output

Description

Validate build output

Usage

validate_build_output(output_dir, platform)

Arguments

Validate a command is available and executable

Description

Shared pattern: resolve a command, abort if not found, run it with a version flag, abort if execution fails. Returns the resolved command.

Usage

validate_command_available(
  command_resolver,
  not_found,
  label = "Command",
  version_arg = "--version"
)

Arguments

Value

Invisibly returns the resolved command path.

Validate configuration values

Description

Checks configuration values and warns about invalid entries.

Usage

validate_config(config)

Arguments

Value

List of validated configuration

Validate a configuration file

Description

Checks a _shinyelectron.yml file for common issues and warns about them.

Usage

validate_config_file(config_path)

Arguments

Value

Invisible TRUE if valid, with warnings for issues.

Validate a container engine is available

Description

Checks that Docker or Podman is installed and can be executed.

Usage

validate_container_available(preference = NULL)

Arguments

Value

Invisible character string with the engine name.

Validate that a directory exists

Description

Validate that a directory exists

Usage

validate_directory_exists(dir, name = "Directory")

Arguments

Validate Electron project structure

Description

Validate Electron project structure

Usage

validate_electron_project(app_dir)

Arguments

Validate icon file for target platform

Description

Checks that the icon file exists and has the correct format for the target platform. Issues warnings (not errors) for format mismatches so the build can continue.

Usage

validate_icon(icon, platform = NULL)

Arguments

Validate multi-app configuration

Description

Validate multi-app configuration

Usage

validate_multi_app_config(config, basedir)

Arguments

Validate Node.js and npm availability

Description

Checks for Node.js and npm, preferring locally installed versions managed by shinyelectron over system installations.

Usage

validate_node_npm()

Value

Invisibly returns a list with node and npm paths and versions.

Validate target platform

Description

Validate target platform

Usage

validate_platform(platform)

Arguments

Validate port number

Description

Validate port number

Usage

validate_port(port)

Arguments

Validate Python app structure

Description

Validate Python app structure

Usage

validate_python_app_structure(appdir)

Arguments

Validate Python is available on the system

Description

Validate Python is available on the system

Usage

validate_python_available()

Value

Invisible character string with the Python command name.

Validate the Python shiny package is installed

Description

Used by the native py-shiny app type. Only checks importability – the export pipeline spawns ⁠python -m shiny run⁠ at runtime on the user's machine, not at build time.

Usage

validate_python_shiny_installed()

Value

Invisible character string with the detected shiny version.

Validate the Python shinylive package CLI is usable

Description

Mirrors the command preference used by convert_py_to_shinylive(): first the shinylive console script on PATH, then ⁠python -m shinylive⁠ as a fallback. Runs --version to confirm the CLI actually executes (an import check is not enough – shinylive ships no ⁠__main__.py⁠, so a package that imports fine can still fail at export time).

Usage

validate_python_shinylive_installed()

Value

Invisible character string with the detected shinylive version.

Validate R is available on the system

Description

Checks that Rscript can be found and executed. Used by the "system" runtime strategy where the end user must have R installed.

Usage

validate_r_available()

Value

Invisible character string with the path to Rscript.

Validate runtime strategy

Description

Validate runtime strategy

Usage

validate_runtime_strategy(strategy)

Arguments

Validate Shiny application structure

Description

Validate Shiny application structure

Usage

validate_shiny_app_structure(appdir)

Arguments

Validate shinylive output

Description

Validate shinylive output

Usage

validate_shinylive_output(output_dir, subdir = NULL)

Arguments

Validate code signing configuration

Description

Checks that required credentials are available when signing is enabled. Issues warnings (not errors) for missing credentials so the build can continue – electron-builder will handle the actual failure.

Usage

validate_signing_config(config, platform = NULL)

Arguments

Validate a slug string

Description

Checks that a slug contains only lowercase alphanumeric characters and hyphens, and is not empty.

Usage

validate_slug(slug)

Arguments

Value

Invisible TRUE if valid, otherwise aborts with an error.

Validate that each language uses a single native runtime strategy

Description

Native strategies (system, bundled, auto-download) share one backend module and one suite-wide runtime detection per language, so a suite may declare at most one distinct native strategy per language. shinylive and container apps use their own backends and are exempt.

Usage

validate_suite_strategies(apps, config)

Arguments

Interactive Configuration Wizard

Description

Walks through setup questions and generates a _shinyelectron.yml configuration file for your Shiny app.

Usage

wizard(appdir)

Arguments

Value

Invisible path to the generated config file.

See Also

init_config() to create a template config file; show_config() to display the merged effective configuration.

Examples

wizard(tempdir())

Write a runtime-manifest.json for the auto-download strategy

Description

Write a runtime-manifest.json for the auto-download strategy

Usage

write_runtime_manifest(
  app_dir,
  app_type,
  platform,
  arch,
  config,
  verbose = TRUE
)