Staying organized is a bitch. Using a separate RStudio project for each distinct task you’re working on is a core organizational principle that works on its own for statistical projects related to classwork or publications. Things get harder, however, when your RStudio project also has a GitHub repository and is a Shiny app hosted on a server like shinyapps.io.
In this post I’m going to begin by describing the easiest way to set up an RStudio project that’s linked to both GitHub and shinyapps.io. This process is exceptionally simple; what’s hard is coming up with a great name that works on all three. In addition, you have to figure out the best place to put the RStudio project in your directory structure. After describing the easy way to set up the project, I’ll go into some excruciating detail on naming and moving RStudio projects.
The exceptionally simple set-up process
These instructions assume you’ve already set up GitHub and shinyapps.io. If not, start with Time to grow up and use Git. Most of your effort should go into the name and folder location for your project. Once you have the name and location, here’s how to proceed:
Do not begin in RStudio! The first step is to create the project in GitHub. The second step is to create the RStudio project. The third step is to link that project to shinyapps.io. Here are the details:
As suggested by Happy Git, go to GitHub.com, make sure you are logged in, and create a new repository. Give it the project name you’ve carefully chosen. Let GitHub create a ReadMe file. Set .gitignore to R. After creating the repository, click the Clone or Download button and GitHub will give you a URL. Copy the URL to your clipboard.
Now in RStudio, use the menu and dialogs to go to File > New Project… > Version Control > Git. Enter the URL you just saved, followed by the project name and folder you’ve carefully chosen.
Inside your new project, select File > New File… > Shiny Web App… and use app as the name.
This will create a folder called app inside your RStudio project. Inside that folder will be one or more files that will also open in RStudio. Click the publish button at the right end of that window (app.R) or one of those windows (ui.R, server.R). In the dialog, change app back to the real project name, and click Publish.
Now you have a folder called app for your Shiny code that’s inside your RStudio project folder. The RStudio project folder is linked to GitHub and the app folder is linked to shinyapps.io. Anything you put in the RStudio project folder is eligible for Git version control but only the files in the app folder are published to shinyapps.io.
Put your effort into project naming
In theory, a single project could have different names in GitHub, RStudio, and on shinyapps.io. Are you crazy? Don’t do it! Six months from now it will take forever to figure out what goes with what.
Project names on GitHub and on shinyapps.io become part of the URL. On GitHub, the project URL will be:
https://github.com/account-name/project-name
On shinyapps.io, the URL will be:
https://account-name.shinyapps.io/project-name/
This means your project name has to be valid in a URL. And that has consequences for upper-case letters and special characters.
Issues with upper-case letters.
Unix filenames are case-sensitive. Help.txt and help.txt are different files in a Unix system. Some folks run RStudio on Unix, so case can be important. In addition, web servers typically run on Unix. However, in practice, GitHub and shinyapps.io are case insensitive, like Windows and Mac OX. This means you could use a name like iframeDemo to organize everything, but you can’t have a second project without the capitalization even if your system supports it (because GitHub and shinyapps.io will consider them the same project.) And, by limiting yourself to lower-case characters, you may save future-you the frustration of debugging an app running on a case-sensitive system that doesn’t work because of filename-case issues.
Issues with special characters.
URLs don’t like to have embedded spaces. So whatever name you select has to be all run together. You can use a multiple-word name by separating the words with hyphens, periods, or, if you don’t mind ugly, underline characters. There are other special characters that are legal, but it’s much easier to limit yourself to those three (periods and underlines are also allowed in R variable names; hyphens are common in URLs and filenames) than to remember what’s legal, what can be made legal, and what can never be legal.
In addition to the 26 lower-case characters, hyphens, periods, and underlines, you can also use the 10 numeric digits in filenames. Unlike R, which won’t let you begin a variable name with a number, filenames in URLs can start with a number or just be a number. For example, 1 is a legal filename, even though it’s completely uninformative.
Issues with renaming projects.
Renaming RStudio projects is a multi-step process. When the project is linked to GitHub or shinyapps.io, the number of steps increases. Multiple steps make it easy to break things, which is awful for keeping things organized.
Put your effort into coming up with a great name to begin with. If you come up with a better name for a project later and want to change it, you can minimize the embedded frustration of the task by just starting over with a new linked project that uses the better name (using the process described above) and then copying your existing work into the new project folder.
Folder structure and moving RStudio projects
Each RStudio project has its own folder that can be anywhere in your directory structure, which is good for keeping things organized. But beware of folder structures like this one:
Exercise A/ analysis/ (RStudio project here for Exercise A) data/ plots/ Exercise B/ analysis/ (RStudio project here for Exercise B) data/ plots/
Here all the projects have the same name, analysis, which isn’t useful. Instead, put everything related to a project inside the RStudio project folder (in other words, the RStudio project folder should be the top-level folder for a project, not an inner folder). Among other things, if you’re using Git, this folder structure provides the entire project with version control.
The link between GitHub and an RStudio project is based on the GitHub URL, which won’t change if you move the project folder. And after you’ve published an app to shinyapps.io, you’ll find a new folder called rsconnect in your app folder. It holds the information RStudio needs to connect to shinyapps.io, so moving the whole project to a new place in your own computer’s folder structure won’t break that link either.
However, RStudio itself remembers the location of project folders for the drop down project menu that’s at the right end of its second-level, icon-based menu bar. Moving a project will break the link between the menu and the project. So to move a project folder, close RStudio, move the folder, open RStudio, and select the project from that drop down menu. You’ll get a message that the project has moved or has been deleted and the drop down will forget about that project.
Then, using the RStudio File > Open Project… command, open the new project folder and select the project-name.Rproj file inside that folder. This will open the project and add its new location to RStudio’s drop-down project menu.
And that’s how you keep all this stuff organized.