React.js Front End Setup

In these instructions, we’ll guide you through creating a basic React.js project.

  1. Log into http://kgcoe-git.rit.edu using your RIT username and password. You should find yourself already assigned to a group. If you are not in a group, get in touch with your instructor.
  2. In your group, we have created a project for you called rest-abc123 where abc123 is your username. Note that you have access to 3-4 other students’ repositories. You are going to be pushing code to your own repository and making comments on other students’ repositories. (See our FAQ on working with other students’ code
  3. Clone your project repository locally using your favorite Git client. (See our Git page for some helpful resources.)
  4. Install Node.js. We recommend the latest long term support version (v12.16.x at the moment). However, if another project on your system requires the development version of Node.js, that is fine. Managing multiple versions of Node.js on a single system is often painful.
  5. The installer will ask if you want to install C/C++ compiler tools. Do this. Many Javascript modules have native code that should be compiled locally.
  6. To test that Node.js is installed, go to the command line. Run node --version. You should see the version that you expect to be installed.
  7. We’ll use the project Create React App to get started. On the command line in the folder where you keep your code, run npx create-react-app abc123-react. This creates a folder and a ton of files.
  8. If all goes well, you should be able to run npm start (or yarn start - Yarn is a simpler alternative to the standard node package manager npm). This will start a development server locally, and it fires up a browser automatically at http://localhost:3000
  9. Now is a good time to commit to Git. Commit this starter code and push to your repository on GitLab. Make sure that worked before moving forward.
  10. We need to make one small change to the starter code. In package.json, add the key-value pair homepage: "." to the top-level settings. We’ll explain in the starter code walkthrough. So the code looks like this:
{
  "name": "abc123-react",
  "version": "0.1.0",
  "homepage": ".",
  // lots of other stuff after this
}
  1. Let’s test out modifying code locally and then showing up in the browser. Open up src/App.js and change the text Edit src/App.js and save to reload to something else. Switching back to your browser, you’ll see the change is updated (it should auto-reload, but this can be a little flakey).
  2. Take a tour of the starter code for a bit. Make a guess in your mind as to what each file does, then check your guess against our explanation down below in our walkthrough. Don’t rush this step. Knowing all of these pieces is important.
  3. For the first few iterations of this project, we will essentially be ignoring React.js. We just started with this code because we know we are heading there. For now, go to src/App.js and delete everything inside of the <div className="App">…</div>. Also, to suppress a warning, comment out the logo import line. Thus, your React app will look more like this:
import React from 'react';
// import logo from './logo.svg';
import './App.css';

function App() {
  return (
    <div className="App">
    </div>
  );
}

export default App;
  1. Your app now looks completely barren in the browser. To make sure we’re still working, go to index.html and add <h1>We're still here!</h1> right below the <body>. Here is where you will be doing a good chunk of your work for the next week or two.
  2. Commit in Git and push to your GitLab repository.
  3. Next, let’s get this up and running on our CI. For this project, we’re going to be emphasizing continuous delivery, which means that every build that succeeds on the repository will be posted to a website. Fortunately, the GitLab pages feature allows us to post code from our repository into a static site associated with the project. So let’s make use of that. Use this setup for your .gitlab-ci.yml
image:
  name: node:12

cache:
  paths:
  - node_modules/

before_script:
  - yarn install 
  - node --version

pages:
  stage: deploy
  script:
    # This magical incantation will inject a build version just before </body>"
    - sed -i "s|</body>|<small>Built on GitLab branch <code>$CI_COMMIT_REF_NAME</code> commit <code>$CI_COMMIT_SHORT_SHA</code> $(date)</small></body>|g" public/index.html
    - npm run build   # Do a production build to build/ folder
    - rm -rf public   # React public/ shouldn't conflict with GitLab public/
    - mv build public # Move to the directory GitLab pages expects
  artifacts:
    paths:
    - public
  1. Let’s break down the above config.
    • For image: we’re just using a standard nodejs image from Dockerhub - nothing special like we had on our previous projects.
    • The cache: key is for speeding up our builds - we don’t want yarn to have to download ~150mb of stuff every time we build, so we save the node_modules directory.
    • For stage: we’re using deploy instead of test - GitLab has various stages and so far we have only used test. There’s all kinds of logic you can build in there, e.g. “don’t deploy unless test passes”.
    • The script: line starting with sed has a magical command using Bash that needs explanation. When we build the site and put it on GitLab pages, we want to know what was actually posted. For example, a build might fail so then you’re looking at that previous commit’s build. Feel free to use, not use, or customize this as you see fix. This line isn’t strictly necessary, but trust me, you’ll be glad you have it when you realize you’re looking at an old build.
    • The npm run build makes a production build, which bundles and minify the project into as few and smallest files as possible with some backwards compatibility.
    • The rm command removes our React public folder since it would conflict with GitLab’s public folder.
    • The mv command moves our build to where GitLab expects it to be.
    • The artifacts: part tells GitLab pages to save the public folder after our build finishes - so it can be used for GitLab pages.
    • You should also know that, in order to post to a GitLab pages site, the job must be called pages - that’s how it knows to put everything on a static site.
  2. After reviewing the CI build settings, commit and push to your repo. Check that the build passes.
  3. Once the build has passed, go to your project on GitLab, and go to Settings > Pages to see the URL that your code is posted at. Go there and keep note of that URL for the future so your teammates can see your latest build. Note that there’s our build information at the bottom of the page, whereas we don’t have that in our development build. Also note that it’s UTC time, which is four hours ahead of New York’s time zone.
  4. At this point, you essentially have a basic static site with lots of tools at your fingertips waiting to be used. You have a few options for learning new material:
    • Mozilla’s MDN web docs is my favorite source for all things web. They have definitive answers for even the most technical and obscure issues. The guides are well-written for mere mortals (usually). Everything is up to date, since it’s maintained by the browser development teams themselves. Ordinarily writing this quality is only found in textbooks - and for us it’s free. We will be covering this material in lecture as well, but you’ll be coming here for lots of details.
    • CSS Tricks is another well-written, well-curated site explaining a lot of front-end concepts and details. Their guide to flexbox, for example, is incredibly helpful.
    • Getting Started in React.js is a great tutorial. If you feel comfortable with Javascript and CSS, then feel free to get ahead and dive into React.js. Note that we won’t be requiring React.js to our project until react3, but you are welcome to incorporate it early on.

React.js Starter Code Walkthrough.

  • node_modules - this directory is infamous. Yes, after creating a basic React.js app that directory now has over 33 thousand files! This is all of the code that the framework depends on, which is the culimination of a massive community of open source developers. No need to ever touch this directory yourself - using yarn or npm commands essentially manages this directory. In a pinch, deleting this directory and reinstalling is the node.js equivalent of “have your tried turning it off and on again?". Also: no need to put this in your Git repo - hence our .gitignore file ignoring it.
  • .gitignore - you’ve seen this before. This one in particular is anticipating that we’re using a lot of things we haven’t turned on yet.
  • public/ is the directory where we keep our static content. Anything that just needs to be copied over to the final site should go here: images, metadata, etc. Anything that needs preprocessing, compiling, bundling, minifying, or any kind of munging does NOT go here.
  • public/favicon.ico - this is that little icon you see in your browser tab. Perhaps the only time in your life where people still use the .ico image format (other formats are allowed by the way, and ICOs are just bundles of PNGs with zooming metadata).
  • public/index.html - the root of our website. Most web servers are configured that when a url goes to a directory, then it opens up index.html. You will be doing a good amount of work here for the first few weeks of the project, then that work will move out of this file and into the src/ folder as we start using React.js
  • public/manifest.json - this is a configuration file that gives various metadata required for React to use some extra browser features, learn more if you like.
  • public/robots.txt - this is a file that is a convention for how a (friendly) search engine should treat your website. It is just advice for doing search engine optimization for Google, Bing, etc. This one happens to default to “index everything on our site”.
  • src/ is the root of our React app. When we get to using React.js, we’ll be living most of our development lives here. Notice how we have various file types in here.
  • src/App.css is our main Cascading Stylesheet. Why isn’t this in public/? Because React will actually check your CSS for validity, and you can also do some preprocessing with packages like SASS to make your CSS cleaner to read and easier to maintain.
  • src/App.js is the top-level React component. For now it does nothing.
  • src/App.test.js is the React equivalent of a unit test. One of the most useful parts of React is that it encourages (nay forces) you to break your system down into components, which naturally means that more of your system is testable.
  • src/index.js is the entrypoint to our React project. Note how this is what instantiates App.
  • src/logo.svg is in the src folder, but it could also probably be in the public/ folder. SVG files are XML, so React might do some validation against it too as part of the build process, so that might be why it’s here. Or, perhaps the code will want to modify the SVG on the fly, in which case the SVG internal code itself is accessible to React.js. Typically, we put SVG files into src/ and not public/ for this reason.
  • src/serviceWorker.js has some boilerplate for improving performance of the React runtime. It also does some extra work to make development easier locally, i.e. when deployed on localhost. In a real system you might tweak this to your needs, but we won’t be doing any work here.
  • src/setupTests.js is the entrypoint for the testing framework, in this case this is what invokes our testing framework Jest
  • package.json - this is used by yarn and npm to manage our packages, as well as some configuration options for React builds. This file and yarn.lock are consulted when managing node_modules. We made a small edit earlier for homepage - this setting tells React that we want our links to all be relative to the root directory, not absolute to the URL. This means that our site can be deployed at any URL path (e.g. both localhost:3000/ and example.com/foo/bar/baz/). This is especially helpful since GitLab pages deploys the site at a deeper path than our development server does. Learn more if you like.
  • yarn.lock is a file that “freezes” what version of the packages you are using. For example, your package.json might say use package foo 1.0, but then package foo comes out with 1.0.1 and then 1.0.2. So which one are you actually using? The yarn.lock file is the definitive authority on that. Yarn consults this file when figuring out what to put in node_modules.
  • README.md has lots of React-related stuff to help you on your way.