React Starter Project

Acknowledgements

This is a LEANSTACKS solution.

Getting Started

This is a Single-Page Application (SPA) user interface application authored in JavaScript using the React framework.

Languages

This project is primarily authored in:

• ES2020 JavaScript with syntactic sugar via Babel
• JSX
• SASS

Installation

Fork the Repository

Fork the GitHub repo. Clone the project to the host machine.

Dependencies

This project requires the following global dependencies on the host machine:

• Node v14 (lts/fermium)
• Yarn

After installing the global dependencies, initialize the project. Open a terminal window, navigate to the project base directory and issue this command:

yarn install

Yarn retrieves all project dependencies and installs them into the /node_modules sub-directory.

Editors

You may use your preferred text editor. Atom or VS Code are recommended.

Running

The project uses Yarn commands for build, test, and local debugging workflow automation. The following Yarn commands are defined.

Start

The start command performs the following workflow steps:

• starts the Webpack development server
• builds the application and loads it into memory
• watches source directories for changes
• republishes source files when changes occur
• reloads the application in the browser when changed source files are republished

The start command is designed to allow engineers the means to rapidly make application changes on their local machines. This task is not intended for use in a server environment.

To execute the start command, type the following at a terminal prompt in the project base directory:

yarn start

Open a browser and go to http://localhost:9000/ to use the application.

To stop the Webpack development server, press ctrl-C in the terminal window.

Test

The test command performs the following workflow steps:

• executes tests once and exits

The test command is designed to allow engineers the means to run all tests contained within *.test.js files located in the /src/tests/ sub-directory.

To execute the test command, type the following at a terminal prompt in the project base directory:

yarn test

To start the test environment and re-execute tests as source files are modified, use the --watch option.

yarn test --watch

To stop the test environment in watch mode, press q in the terminal window.

Build

The build command performs the following workflow steps:

• starts the Webpack process
• creates a clean distribution /dist directory
• copies all static assets to the distribution directory
• transpiles, ugilifies, minifies, and maps source files into distribution bundles
• injects the distribution bundles into link and script tags within the index.html file

To execute the build command, type the following at a terminal prompt in the project base directory:

yarn build

Deployment

This project is ideally suited to be hosted from a static web server (e.g. Apache or Nginx) or from a CDN (e.g. AWS CloudFront).

To prepare the application distribution for deployment, run the build Yarn command documented above. Next, take all of the files and directories from the /dist directory and deploy them to your hosting environment.

Web Server Configuration

Fallback to index.html

Routed applications must fall back to index.html. That means, if you are using SPA routing you must configure the static web server to return to the base html page (index.html) when the router is asked to serve a route which does not exist.

A static web server commonly returns index.html when it receives a request for http://www.example.com/. But it returns a 404 - Not Found error when processing http://www.example.com/greetings/109 unless it is configured to return index.html instead.

Each static web server is configured for fallback in a different way. Here are a few examples for common scenarios.

Webpack Development Server

historyApiFallback: {
    disableDotRule: true,
    htmlAcceptHeaders: [text/html', 'application/xhtml+xml']
}

Apache

Add a rewrite rule to the .htaccess file as illustrated below.

RewriteEngine On
  # If an existing asset or directory is requested, go to it as it is
  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
  RewriteRule ^ - [L]
  # If the requested resource doesn't exist, use index.html
  RewriteRule ^ /index.html

NGinx

Use try_files as described in the Front Controller Pattern Web Apps documentation.Getting Started pages

try_files $uri $uri/ /index.html;

IIS

Add a rewrite rule to web.config, similar to the one illustrated below.

<system.webServer>
  <rewrite>
    <rules>
      <rule name="Angular Routes" stopProcessing="true">
        <match url=".*" />
        <conditions logicalGrouping="MatchAll">
          <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
          <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
        </conditions>
        <action type="Rewrite" url="/src/" />
      </rule>
    </rules>
  </rewrite>
</system.webServer>

Docker

This repository contains a sample Dockerfile which illustrates how to build a React SPA into a Docker image.

You may view and pull the published skeleton-ui-react Docker images on DockerHub.

Prerequisites

These instructions assume that you have the Docker CLI installed on your local computer. See the Docker Guides to get started with Docker.

Build

To build a Docker image for this project, run the following command in the root directory of this project:

docker build -t skeleton-ui-react:latest

Pull

To pull the latest skeleton-ui-react Docker image from the LeanStacks repository on DockerHub, run the following command:

docker pull leanstacks/skeleton-ui-react:latest

Run

To run the Docker image on your local machine, run the following command:

docker run -p 9000:80 leanstacks/skeleton-ui-react:latest

Note: The command above uses the official image published by LeanStacks to DockerHub. If you have built an image locally, you may substitute the name of your image.

This command will run the Docker image in the foreground, allowing your to terminate the process by pressing ctrl-C.

Open a browser and go to http://localhost:9000/ to use the application.

To stop the Docker container, press ctrl-C in the terminal window.

Technology Stacks

Application

React
React Router
React Redux
Redux
Redux Thunk
Axios
Lodash
Luxon
Bootstrap
Font Awesome
Google Fonts
JavaScript
SASS

Test

Jest
Enzyme
Redux Mock Store

Build

Babel
Webpack
Yarn