/r-shiny-electron-app

:memo: Guide to desktop app creation using R Shiny and Electron

Primary LanguageJavaScriptMIT LicenseMIT

How to Make an R Shiny Electron App

A setup guide by L. Abigail Walter
Instructions adapted from Travis Hinkelman
R Shiny Electron template created by Dirk Shumacher

Introduction

Motivation: In February 2020, I was unable to create a standalone desktop app using an R Shiny Electron template via Dirk Shumaker's original repo or Travis Hinkelman's fork. I avoided the warnings created with their methods by using npx instead of npm, and by adding file index.js that redirects, and wanted to share this information with other users.

Objective: Write a comprehensive guide for anyone interested in creating an R Shiny Electron app. This guide assumes the user has intermediate R coding skills, intermediate ability to use the terminal, and little to no experience with JavaScript.

Acknowledgements: I credit Dirk Shumacher for writing most scripts in this repo, only some of which I edited with only minor changes. In addition, Travis Hinkelman created the groundwork for this guide, which I made changes to in order to avoid warnings and reports of vulnerabilities and to ultimately allow the app to launch.

Note: I recommend building your app using macOS if possible; it is much simpler than Windows.

Navigation

Getting started on macOS

All of the following steps can be run exclusively in the RStudio terminal

Steps to get your computer ready:

  1. Install Node.js: https://nodejs.org/en/
  2. Install Electron Forge using npm (npm is installed with Node.js)
    • In the R terminal, run npm i -g @electron-forge/cli
    • If there's a permission error, run sudo npm i -g @electron-forge/cli
  3. Check your versions of node node -v and npm npm -v. For this guide, I will be using node v13.9.0 and npm v6.13.7. If your installations do not match mine and you experience problems with these steps, try downgrading or upgrading (see Troubleshooting section below).
  4. Open an existing R project, create a new one, or initialize a project by cloning a git repo.

Advanced macOS steps

Start here if you have all of the dependencies installed:

  1. Make sure your directory is in R project folder you're ready to turn into an app.
    • Run pwd on the command line to check what directory you are in.
    • If you're not in the right folder, change your directory using cd example/file/path with the example path replaced with the appropriate path to your project.
  2. In your project directory, install Electron locally by running npx create-electron-app appNameHere. Replace appNameHere with whatever you want to name your app.
    • Note: Your app cannot be titled "app".
  3. In your appNameHere folder, delete folder src.
  4. Move files (I typically use the R file pane gui) to your new app folder, including:
  • get-r-mac.sh
  • add-cran-binary-pkgs.R
  • start-shiny.R
  • Folder shiny from this repo, containing:
    • shiny/app.R
  • Folder src from this repo, containing:
    • src/failed.html
    • src/helpers.js
    • src/index.css
    • src/index.js
    • src/loading.css
    • src/loading.html
    • src/main.js
  • Note: File app.R is whatever R Shiny script you want to launch in your application. You can use the example provided in this repo or use your own.
  1. Change your directory to your new app folder cd appNameHere
  2. Install R locally:
    • First, check the version of R on your machine. In the R console, run version
    • Edit get-r-mac.sh, replacing version numbers in the link https://cloud.r-project.org/bin/macosx/R-3.6.2.pkg with the version you are running.
      • Important: The R version used to make the shiny app and the version installed locally must match. The app included in this repo was created in R v3.6.2.
    • Once you save the file, run the shell script in the terminal sh ./get-r-mac.sh
  3. If you don't have the automagic package installed, run install.packages("automagic") in the R console.
  4. In the R terminal, run Rscript add-cran-binary-pkgs.R to get packages for R.
  5. Add additional dependencies to package.json. Replace the dependencies listed at the end of the script with the following. Take care not to paste over the final ending bracket } of the .json file.
    "dependencies": {
      "axios": "^0.19.2",
      "electron-squirrel-startup": "^1.0.0",
      "esm": "^3.2.25",
      "execa": "^4.0.0"
    },
    "devDependencies": {
      "@babel/core": "^7.8.4",
      "@babel/plugin-transform-async-to-generator": "^7.8.3",
      "@babel/preset-env": "^7.8.4",
      "@babel/preset-react": "^7.8.3",
      "@electron-forge/cli": "^6.0.0-beta.50",
      "@electron-forge/maker-deb": "^6.0.0-beta.50",
      "@electron-forge/maker-rpm": "^6.0.0-beta.50",
      "@electron-forge/maker-squirrel": "^6.0.0-beta.50",
      "@electron-forge/maker-zip": "^6.0.0-beta.50",
      "electron": "8.0.2",
      "eslint": "^6.8.0",
      "eslint-config-airbnb": "^18.0.1",
      "eslint-plugin-import": "^2.20.1",
      "eslint-plugin-jsx-a11y": "^6.2.3",
      "eslint-plugin-react": "^7.18.3",
      "eslint-plugin-react-hooks": "^1.7.0",
      "fs-extra": "^8.1.0"
      }

Note: Modules are updated frequently and as such are subject to changing version numbers. It is important to double-check that these dependencies are up-to-date by replacing their version numbers with any newer version numbers. You can accomplish this by manually searching the module names at https://www.npmjs.com/

Note: We are using "eslint-plugin-react-hooks": "^1.7.0" because using the latest v2.4.0 throws a warning.

Optional: If you have not added a field in the package.json for repository information, you will see a warning when running npm install. This is not a serious warning, but it is good practice to edit the .json with your git repo if you have the time. To do this, insert the following to your package.json:

 "repository": {
  "type": "git",
  "url": "git://github.com/username/repo.git"
  },
  1. Replace the "lint": "echo \"No linting configured\"" line in package.json with "lint": "eslint src --color"
  2. Run npm install to add new dependencies you listed in package.json to the node_modules folder.
  3. Test to see if your app works by running electron-forge start
  4. If the app runs successfully, congratulations! Package and create the .exe on the command line with electron-forge make. Your app can be found in the /out folder.

Getting started on Windows

Unlike the macOS setup, Windows will require the use of multiple terminals, which are specified at each step

Steps to get your computer ready:

  1. Install Node.js: https://nodejs.org/en/
    • Check the box option during the node.js install to also install chocolatey
  2. Skip this step if chocolatey is installed. If chocolatey has not been installed:
    • Open Windows PowerShell with right-click option "Run as Administrator"
    • Follow the installation steps on the chocolatey website
  3. Using chocolatey, install innoextract v1.8 or greater:
    • Re-open Windows PowerShell with right-click option "Run as Administrator"
      • Note: If you just installed chocolatey in Windows PowerShell, you need to close and re-launch the admin shell
    • Run choco install innoextract
      • If innoextract is already installed at a version less than v1.8, run choco upgrade innoextract
  4. In the same Administrator Windows PowerShell, install Electron Forge globally
    • Run npm install -g electron-forge
  5. Install Cygwin
    • During Cygwin install, select wget packages at the 'packages' screen by clicking the arrow in the 'new' clolumn to select the newest version.
  6. Check your versions of node node -v and npm npm -v using any terminal. For this guide, I will be running node v13.9.0 and npm v6.13.7. If your installations do not match mine and you experience problems with these steps, try downgrading or upgrading (see Troubleshooting section below).
  7. Open an existing R project, create a new one, or initialize a project by cloning a git repo.

Advanced Windows steps

Start here if you have all of the dependencies installed:

  1. Make sure your directory is in R project folder you're ready to turn into an app.
    • In Windows PowerShell, run pwd on the command line to check what directory you are in.
    • If you're not in the right folder, change your directory using cd C:\Users\Name\Desktop\gitFolderName with the example path replaced with the appropriate path to your project.
  2. In your project directory, install Electron locally:
    • Using Windows PowerShell, run npx create-electron-app appNameHere
    • Replace appNameHere with whatever you want to name your app.
      • Note: Your app cannot be titled "app".
  3. In your appNameHere folder, delete folder src.
  4. Move files (I typically use the R file pane gui) to your new app folder, including:
  • get-r-win.sh
  • add-cran-binary-pkgs.R
  • start-shiny.R
  • Folder shiny from this repo, containing:
    • shiny/app.R
  • Folder src from this repo, containing:
    • src/failed.html
    • src/helpers.js
    • src/index.css
    • src/index.js
    • src/loading.css
    • src/loading.html
    • src/main.js
  1. In Windows PowerShell, change your directory to your new app folder cd appNameHere
  2. Install R locally:
    • First, check the version of R on your machine. In the R console, run version
    • Edit get-r-win.sh, replacing version numbers in the link https://cloud.r-project.org/bin/windows/base/R-3.6.2-win.exe with the version you are running if you made the app.R, or the version of R that was used to make the app.
      • Important: The R version used to make the shiny app and the version installed locally must match. The app included in this repo was created in R v3.6.2.
    • Open the Cygwin terminal. Change your directory by 1) typing cd, 2) opening File Explorer and navigating to your app folder, then 3 ) dragging the app folder itself to the Cygwin terminal window to paste the file path. Run the command.
      • Example: cd /cygdrive/c/Users/Abby/Desktop/git/r-shiny-electron-app/appNameHere
    • In Cygwin, run sh ./get-r-win.sh
      • If you got an error: you will likely need to convert get-r-win.sh to Unix
      • To fix error ./get-r-win.sh: line 5 --output-document: command not found
        • Download Notepad++ if you don't already have it
        • Open get-r-win.sh in Notepad++
        • Go to Edit -> EOL Conversion -> Unix (LF)
        • Save the script
        • In Cygwin, re-run sh ./get-r-win.sh
  3. In the R console, install.packages("automagic") if this package is not already installed.
  4. Switch to the RStudio terminal and make sure your directory is in the appNameHere folder. Get packages for R by running Rscript add-cran-binary-pkgs.R
  5. Using R, edit package.json to add additional dependencies. Replace the dependencies listed at the end of the script with the following. Take care not to paste over the final ending bracket } of the .json file.
    "dependencies": {
      "axios": "^0.19.2",
      "electron-squirrel-startup": "^1.0.0",
      "esm": "^3.2.25",
      "execa": "^4.0.0"
    },
    "devDependencies": {
      "@babel/core": "^7.8.4",
      "@babel/plugin-transform-async-to-generator": "^7.8.3",
      "@babel/preset-env": "^7.8.4",
      "@babel/preset-react": "^7.8.3",
      "@electron-forge/cli": "^6.0.0-beta.50",
      "@electron-forge/maker-deb": "^6.0.0-beta.50",
      "@electron-forge/maker-rpm": "^6.0.0-beta.50",
      "@electron-forge/maker-squirrel": "^6.0.0-beta.50",
      "@electron-forge/maker-zip": "^6.0.0-beta.50",
      "electron": "8.0.2",
      "eslint": "^6.8.0",
      "eslint-config-airbnb": "^18.0.1",
      "eslint-plugin-import": "^2.20.1",
      "eslint-plugin-jsx-a11y": "^6.2.3",
      "eslint-plugin-react": "^7.18.3",
      "eslint-plugin-react-hooks": "^1.7.0",
      "fs-extra": "^8.1.0"
      }

Note: Modules are updated frequently and as such are subject to changing version numbers. It is important to double-check that these dependencies are up-to-date by replacing their version numbers with any newer version numbers by manually searching the module names at https://www.npmjs.com/

Note: We are using "eslint-plugin-react-hooks": "^1.7.0" because using the latest v2.4.0 throws a warning.

Optional: If you have not added a field in the package.json for repository information, you will see a warning when running npm install. This is not a serious warning, but it is good practice to edit the .json with your git repo if you have the time. To do this, insert the following to your package.json:

 "repository": {
  "type": "git",
  "url": "git://github.com/username/repo.git"
  },
  1. Replace the "lint": "echo \"No linting configured\"" line in package.json with "lint": "eslint src --color"
  2. In Cygwin, run npm install to add new dependencies you listed in package.json to the node_modules folder.
  3. Test to see if your app works by running electron-forge start in the Cygwin terminal.
    • To stop running the app, press Ctrl+C
  4. If the app runs successfully, congratulations! Package and create the .exe on the command line with electron-forge make. Your app can be found in the /out folder.

Getting started on Linux

These steps were created on and for Linux Mint 18, but should work with any Ubuntu edition

Steps to get your computer ready:

  1. Install Node.js using the terminal sudo apt install nodejs-legacy
  2. Your Node.js version is probably behind, so next install a version manager sudo npm install -g n
    • Upgrade Node.js
      • To the most recent version, which at present is v13.9.0, by running sudo n 13.9.0
      • Or to the most recent stable version using sudo n stable
  3. Install Electron Forge
    • Run npm i -g @electron-forge/cli
    • If there's a permission error, run sudo npm i -g @electron-forge/cli
  4. Check your versions of node node -v and npm npm -v. For this guide, I will be using node v13.9.0 and npm v6.13.7. If your installations do not match mine and you experience problems with these steps, try downgrading or upgrading (see Troubleshooting section below).
  5. Open an existing R project, create a new one, or initialize a project by cloning a git repo.

Advanced Linux steps

Start here if you have all of the dependencies installed:

  1. Make sure your directory is in R project folder you're ready to turn into an app.
    • Run pwd on the command line to check what directory you are in.
    • If you're not in the right folder, change your directory using cd example/file/path with the example path replaced with the appropriate path to your project.
  2. In your project directory, install Electron locally by running npx create-electron-app appNameHere. Replace appNameHere with whatever you want to name your app.
    • Note: Your app cannot be titled "app".
  3. In your appNameHere folder, delete folder src.
  4. Move files (I typically use the R file pane gui) to your new app folder, including:
  • get-r-linux.sh -- shell script adapted from RStudio Documentation by me
  • add-cran-binary-pkgs.R
  • start-shiny.R
  • Folder shiny from this repo, containing:
    • shiny/app.R
  • Folder src from this repo, containing:
    • src/failed.html
    • src/helpers.js
    • src/index.css
    • src/index.js
    • src/loading.css
    • src/loading.html
    • src/main.js
  • Note: File app.R is whatever R Shiny script you want to launch in your application. You can use the example provided in this repo or use your own.
  1. Change your directory to your new app folder cd appNameHere
  2. Install R locally:
    • First, check the version of R on your machine. In the R console, run version
    • Open get-r-linux.sh and edit the line export R_VERSION=3.6.2 with the version you are running if you made the app.R, or the version of R that was used to make the app.
      • Important: The R version used to make the shiny app and the version installed locally must match. The app included in this repo was created in R v3.6.2.
      • Note: I only cover installing R locally on Ubuntu and Ubuntu-based editions. To install R locally on another Linux distribution, cheeck out the R Installation and Administration Manual and readme files in the R directories. Good luck!
    • Save your edit(s) in get-r-linux.sh and then run the shell script in the terminal sh ./get-r-linux.sh
      • Note: This step may take a while (5-15 mins).

To be continued -- local R install still not 100%

Troubleshooting

Steps for macOS, Windows, and Linux

  • To change your version of Node.js, install n with npm. This module will enable you downgrade or upgrade Node.js if there is an issue running it at your current version. In the terminal, run sudo npm install -g n to install.
    • Example: To change to Node v10.16.3 run sudo n 13.9.0

Back to top