Setting Up a React Project

This is part 1 of a tutorial series in which we create a simple React project and publish it to GitHub pages. It is designed for beginners with a JS background and familiarity with basic programming concepts. To view the entire series, see HERE.

In this tutorial, we create a very simple React project and deploy it to GitHub Pages. The idea is to show step-by-step, the sequence involved in creating a React application from scratch. We use Macbook for this tutorial but if you have a PC or Linux machine, you should be fine.


The tools listed below are required to follow this tutorial:

Create Project, Install Dependencies

Open up the terminal and navigate to the desktop or wherever you do development work. Then create a new directory called “react-proj” and change directory into it. Once there, create a new Node project by typing npm init -y which will generate a package.json file containing all default values. To this point, the terminal commands should look like this (click to enlarge):

Next, we install the following modules to support react, webpack, and babel. Webpack is a bundler which runs tasks that bundle our React code from ES6 and JSX into standard JavaScript. ES6 is still not compatible with all browsers and JSX is not valid JavaScript at all so in order to run our React code, we have to transpile it into regular JS and run that instead. The installation commands from the terminal are shown below (commands hi-lighted in GREEN):

click to enlarge

Finally, we install the babel modules which will actually perform the transpiling from ES6 and JSX to standard JavaScript:

click to enlarge

Now that we have the required modules installed, it’s time to set up the project file structure. Start with creating an index.html: touch index.html

Then create a webpack config file: touch webpack.config.js

Then create an ‘src’ directory and cd into it. Once there, create and app.js file:

$ mkdir src
$ cd src
$ touch app.js

Your final directory structure should look like this:

First React Component

At a basic level, a React project consists of a series of smaller visual units called “components”. A component can be thought of as a custom HTML tag in which you decide the actual html that gets rendered when the component is used. A React frontend is a series of components joined together to create the page. In our project, we created our first component in the SRC directory called “app.js” — as the extension indicates, the component is written in JavaScript. To get started, we import the required modules:

import React, { Component } from ‘react’
import ReactDOM rom ‘react-dom’

Then we define the class and name for our component which in this case will be called “App”. Finally, we render the component on the main page by mounting it on div tag with the id “app” at which point, React will inject our contents inside. See image below:

click to enlarge

Several things are worth noting here. First, we import modules as well as parts of a module. In line 1, we use { Component } to import a sub-module from the React library. This is a new ES6 feature in which we can import individual classes and functions. Next, we create a class called “App” which subclasses the Component class from React. Within that, we override a function called “render” which returns the actual HTML that appears when the component is used. Finally, on line 14, we inject the code into an HTML template by rendering it inside of a div tag whose ID is ‘app’.

The most important consideration of this code is the render() override. It is where we literally determine what shows up when the component is used. The return value (lines 7–9 inclusive) looks like HTML but this is actually JSX — the JavaScript Extension that was created to make HTML easier to write inside of JavaScript code. Since this is not valid JS, it is eventually transpiled into regular JS. Speaking of…


It is now time to swing over to the webpack.config.js file to set up the transpiling configuration. Open up webpack.config.js in your editor and type the following: 
var webpack = require(‘webpack’)
var path = require(‘path’)

Then fill out the rest of the file so it looks like this:

click to enlarge

At first glance, this looks somewhat confusing but there are only a couple lines that really matter at this point and those are line 7 and line 10. In line 7, we tell webpack where to find the entry point of our React code and in line 10, we tell webapck where to put the results of the transpiled code — typically called the bundle. The bundle is the regular JavaScript code that actually runs in the browser. Notice there is no ‘build’ directory in our project structure. Webpack will create one for us after the bundle is done executing and place the results there. the bottom half of the config file is where is tell webpack what ‘loaders’ to use with corresponding options. For now, you will almost certainly do it this way every time so it’s basically boilerplate code.

To run webpack, navigate to the top level of the project in your terminal and open a new tab by typing CMD-T. In the new tab, type webpack -w and wait for a few seconds. If all goes well, you should see this:

click to enlarge

If you don’t see that, it’s usually a typo so go back to the webpack.config.js for OR the app.js file and double check your spelling. Do not proceed until the webpack command successfully runs.

Rendering the Project

Now that we have the React code set up and the build script running, it is time to show our code in the browser (finally). Open up the index.html file in your text editor and set up some basic html to look like the following:

click to enlarge

Notice we import the bundle.js rather than the app.js in line 9 — this is because the transpiled code is what runs in the browser. Also notice that there is a div tag with the ID ‘app’ — this is the tag that will render our React app, specifically the app.js code. Once you have the index.html ready, open it up in a browser and you should see this:

click to enlarge

If you see that, congratulations — you just made your first React application! Check out part 2 of this series where we add more components well as more realistic data to the project.

Download Source Code HERE. IMPORTANT: the node modules are not saved in this project so you have to run npm install in the top level directory when building the project.