From 5dc2d36334f98d3d1624c1eee4ba57fa09e1fa7f Mon Sep 17 00:00:00 2001 From: Jinhwan Kim Date: Sun, 14 Jan 2024 18:45:24 +0900 Subject: [PATCH] Update README.md --- README.md | 203 +++++++++++++++++++++--------------------------------- 1 file changed, 77 insertions(+), 126 deletions(-) diff --git a/README.md b/README.md index dab03cb..0d0591d 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,72 @@ -# How to Make an R Shiny Electron App (2023, M1) +# shiny-electron-template-m1 -A setup guide by L. Abigail Walter
-Instructions adapted from Travis Hinkelman
-R Shiny Electron template created by Dirk Shumacher
-Template & Instruction updated by Jinhwan Kim
+## How to Make an R Shiny Electron App -For windows, see [this repository](https://github.com/zarathucorp/shiny-electron-template-windows-2023) +> [!NOTE] +> +> A setup guide by L. Abigail Walter
+> Instructions adapted from Travis Hinkelman
+> R Shiny Electron template created by Dirk Shumacher
+> Template & Instruction updated by Jinhwan Kim
+> +> For more info, see previous repository
-For more info, see previous repository
+> [!TIP] +> For Windows, see this repository -## Guide article in R-bloggers (based on 2023.03) +## Guide article in R-bloggers (based on 2023.03, may not work in 2024-) Creating Standalone Apps from Shiny with Electron [2023, macOS M1] ------------------------------------------------------------------------- - -## Version Info +## Versions info +![NodeJS](https://img.shields.io/badge/node.js-18.18.0-6DA55F?style=for-the-badge&logo=node.js&logoColor=white) +![NPM](https://img.shields.io/badge/NPM-10.3.0-%23CB3837.svg?style=for-the-badge&logo=npm&logoColor=white) +![RStudio](https://img.shields.io/badge/RStudio-2023.12.0-4285F4?style=for-the-badge&logo=rstudio&logoColor=white) +![R](https://img.shields.io/badge/r-4.3.2-%23276DC3.svg?style=for-the-badge&logo=r&logoColor=white) +![Electron.js](https://img.shields.io/badge/Electron-7.2.0-191970?style=for-the-badge&logo=Electron&logoColor=white) +![macOS](https://img.shields.io/badge/macOS-14.2.1-FFFFFF?style=for-the-badge&logo=apple) -- ![](https://img.shields.io/badge/R-gray?style=for-the-badge&logo=R) 4.3.1 -- ![](https://img.shields.io/badge/Shiny-gray?style=for-the-badge&logo=RStudio) 2023.06.1 Build 524 -- ![](https://img.shields.io/badge/node.js-gray?style=for-the-badge&logo=nodedotjs) v18.15.0 -- ![](https://img.shields.io/badge/npm-gray?style=for-the-badge&logo=npm) v9.8.1 -- ![](https://img.shields.io/badge/macOS-gray?style=for-the-badge&logo=apple) 13.4.1 (c) +--- ## Getting started -### Environment - -All of the following steps can be run exclusively in the RStudio **Terminal** (right to **console**). - -0. Install R, Rstudio. - -1. Install **Node.js**: Offical Page - -2. Install **Electron Forge** using `npm` (`npm` is installed with `Node.js`) - -- In the **Terminal**, run `sudo npm i -g @electron-forge/cli`, (`sudo` requires password) - -3. Check your versions of `node` and `npm` in **Terminal** with `node -v`, `npm -v`. +### A. Environment setup -4. Fork this repository and clone it to your local PC +> [!NOTE] +> All of the following steps can be run exclusively in the RStudio **Terminal** (right to **console**). +> +> so **Terminal** means Rstudio's terminal using Option + Shift + m -### Project +1. Install **R**, **Rstudio**. +2. Install **Node.js**: from offical page +3. Install **Electron Forge** using `npm` (`npm` is installed with `Node.js`) +4. In the **Terminal**, run `sudo npm i -g @electron-forge/cli`, (`sudo` requires password) -5. Open an existing R project, create a new one, or initialize a project by cloning a git repo. +> [!NOTE] +> Check your versions of `node` and `npm` in **Terminal** with `node -v`, `npm -v`. -> 💡 I recommend open cloned `.Rproj` file +5. Give **Star** ⭐, **Fork** this repository to your own account. Then **clone** it to your local PC -6. Make sure your directory is in **R project** folder (from 4.), so you're ready to turn into an app. +### B. Elecron project -- Run `pwd` on the command line to check what directory you are in. (*This may `.../Github/`*) +6. Open an R project with cloned repository's `.Rproj` file. +7. In your project directory (may `Github/shiny-electron-template-m1`), install **Electron** locally by running `npx create-electron-app `. -- 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. +> [!WARNING] +> You can not use `app` as ``
+> Assume using `myapp` in this tutorial -7. In your project directory, install **Electron** locally by running `npx create-electron-app `. +8. In your `myapp` folder, **delete** `src` directory +9. Copy (or move) below files to your `myapp` folder: -> 💡 Your app cannot be titled "app". - -8. In your `` folder, delete folder **src**. - -9. Move files (I typically use the R file pane gui) to your `` folder, including: - -- `get-r-mac.sh`: for install local R into your project locally -- `add-cran-binary-pkgs.R`: for install R packages into your project locally -- `start-shiny.R`: let electron call your shiny app +- `get-r-mac.sh`: For install local R for electron app. +- `add-cran-binary-pkgs.R`: For install R packages into your project locally +- `start-shiny.R`: Let electron call your shiny app - Folder **shiny** from this template, containing: - - `shiny/app.R`: **THIS IS YOUR SHINY APP'S CODE** - - other required file (like `/www`) + - `shiny/app.R`: **THIS IS YOUR SHINY APP'S CODE** -- Folder **src** from this template, containing: - - src/failed.html +- Folder **src** from this template, containing: - src/helpers.js - src/index.css - src/index.js @@ -78,107 +74,62 @@ All of the following steps can be run exclusively in the RStudio **Terminal** (r - src/loading.html - `src/main.js`: configure shiny electron app (like `width`, `height`) -10. Change your directory to your new app folder `cd ` (*This may `.../Github//`*) - -### R +10. Change your directory to new app folder `cd myapp` with **Terminal** -11. Install R locally: - - First, check the version of R on your machine. In the R **Console**, run `version`. +### C. Setup R -> 💡 Your machine's installed R version and newly installed R version (in shiny electron project) MUST same +11. Install local R with `sh ./get-r-mac.sh` + - First, check the version of R on your machine. In the R **Console**, run `version`. -- Once you save the file, run the shell script in the Rstudio **terminal** with `sh ./get-r-mac.sh` (for install R into your project locally) +> [!WARNING] +> **Your PC's R version** and **electron's R version** must same -12. If you don't have the `automagic` package installed, run `install.packages("automagic")` in the **console**. +12. Build `app.R` as your application's code. -### Javascript +> [!NOTE] +> not only `app.R` also other required files for shiny application (like `/www`) -13. Add additional dependencies to `package.json`. +13. If you don't have the `automagic` package installed, run `install.packages("automagic")` in the **console**. -- Replace the dependencies (After **Author**) listed at the end of the script with the following. Take care not to paste over the final ending bracket `}` of the `.json` file. +14. In the Rstudio **terminal**, run `Rscript add-cran-binary-pkgs.R` to get packages for R. -``` js - "repository": { - "type": "git", - "url": "" - }, - "dependencies": { - "axios": "0.27.2", - "electron-squirrel-startup": "^1.0.0", - "esm": "^3.2.25", - "execa": "^5.1.1" - }, - "devDependencies": { - "@babel/core": "^7.22.11", - "@babel/plugin-transform-async-to-generator": "^7.22.5", - "@babel/preset-env": "^7.22.10", - "@babel/preset-react": "^7.22.5", - "@electron-forge/cli": "^6.4.1", - "@electron-forge/maker-dmg": "^6.4.1", - "@electron-forge/maker-zip": "^6.4.1", - "@electron-forge/plugin-auto-unpack-natives": "^6.4.1", - "electron": "^26.1.0", - "fs-extra": "^11.1.0" -``` +> [!NOTE] +> If your shiny application uses not-CRAN packages (like `github` / `bioconductor`), See **Add not-CRAN packages** below. +> -> 💡 This work with 2023.08, do not update dependencies (axios & esm & execa) +### D. Setup electron -### Shiny +15. Change `package.json` as `[fix] packages-json`'s content. And modify **author** information. -14. Build `app.R` as your application's code from Example code. +> [!NOTE] +> Node package's version confirmed in 2024.01 -## Build Shiny Electron App +16. Change `forge.config.js` as `[fix] forge.config.js`'s content. -> 💡 You need to run this steps **whenever** you want to update shiny application. +17. Run `sudo npm install` in **Terminal** to add new dependencies you listed in `package.json` to the **node_modules** folder. -15. In the Rstudio **terminal**, run `Rscript add-cran-binary-pkgs.R` to get packages for R. +### E. Build shiny.exe -> 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 +> [!NOTE] +> You need to run step after this, **whenever** you want to update shiny application. -16. Run `npm install` to add new dependencies you listed in `package.json` to the **node_modules** folder. -17. Test to see if your app works by running `electron-forge start` +18. Test your shiny application work by `electron-forge start` in **Terminal**. -> 💡 If application keep running (not start), Try restart R with `CMD + Shift + 0` / **Session -> Restart R** in Rstudio. then retry 17. +19. If error occurs while `electron-forge make` with `conf.d` Delete `r-mac/fontconfig/fonts/conf.d`. see this [issue](https://github.com/zarathucorp/shiny-electron-template-m1/issues/5) -18. 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. - -Final. Unzip the result `zip file` and run `.app` +20. If the app runs successfully, congratulations! Create the `.exe`(as ZIP) on the `electron-forge make` in **Terminal**. Your app can be found in the **/out** folder. (Strongly recommend to **change read-only property** with mac's `Finder`) ------------------------------------------------------------------------ -## Trouble shooting +## Additionals - Raise an issue, please. -#### Error with require() of ES Module - -- Change `dependencies` (see [issue](https://github.com/zarathucorp/shiny-electron-template-m1-2023/issues/2)) - -``` -"dependencies": { - "axios": "^0.27.2", - "esm": "^3.2.25" - ... -} -``` - -#### Add not-CRAN packages +### Error with require() of ES Module -- manually copy library from your Local's R library to **r-mac/library**, you can check with `.libPaths()` in R console. +It doesn't affect to run shiny. -#### electron-forge start work, but electron-forge make not work +### Add not-CRAN packages -- Change `forge.config.js` (see [issue](https://github.com/zarathucorp/shiny-electron-template-m1-2023/issues/5)) +- manually copy library from your **Local's R library** to **r-mac/library**, You can check Local's R library with `.libPaths()` in **R console**. -```js -module.exports = { - packagerConfig: {}, - rebuildConfig: {}, - makers: [ - { - name: '@electron-forge/maker-zip', - platforms: ['win32', 'darwin'] - } - ] -}; -```