React Slingshot Deploy & Usage Guide

Prerequisites

Required Runtime & Tools

• Node.js: Version 8.0.0 or greater (LTS recommended)
• Git: For repository management
• npm: Bundled with Node.js

Operating System Specifics

macOS:

• Install file watching service to avoid CPU usage issues:

  brew install watchman
  # or
  brew install fswatch
  

Linux:

• Increase inotify watch limit:

  echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
  

Windows:

• Python 2.7: Required for node-gyp dependencies
• C++ Compiler: Visual Studio Express or Visual C++ Tools for Windows Desktop (required for browser-sync compilation)

Editor Configuration

• Disable Safe Write: Configure your editor to disable "safe write" feature to ensure hot reloading works properly (see Webpack guide)

Installation

Option 1: Use GitHub Template (Recommended)

1. Click the green "Use this template" button on the repository page
2. Enter your repository name and description
3. Clone your new repository:

   git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
   cd YOUR_REPO_NAME
   

Option 2: Clone Directly

git clone https://github.com/coryhouse/react-slingshot.git
cd react-slingshot

Run Setup

Execute the automated setup script to install dependencies and configure your project:

npm run setup

This will:

• Install npm dependencies
• Prompt for project details (name, version, author, license, description)
• Remove the original git repository (optional)
• Update package.json with your settings

Note: If you skip npm run setup, run npm install manually, then manually update package.json and remove the .git directory if desired.

Configuration

Environment Variables

• Ensure NODE_ENV is NOT set to production on your development machine. If set, development dependencies won't install.
• Check your current setting: echo $NODE_ENV (Unix) or echo %NODE_ENV% (Windows)
• If set to production, unset it before installing dependencies.

Project Metadata

During npm run setup, you'll configure:

• Project name
• Version (default: 0.1.0)
• Author
• License (default: MIT)
• Description

These values are written to package.json.

Source Structure

• Source code: /src
• Tests: Placed alongside files under test (e.g., Component.js and Component.test.js)
• Production build: /dist (generated, not committed)

Build & Run

Development Mode

Start the development server with hot reloading, linting, and automated testing:

npm start

For silent mode (suppresses unnecessary messages):

npm start -s

Features:

• Webpack dev server with hot module replacement
• Source maps via cheap-module-eval-source-map
• ESLint running on save
• Tests running automatically
• Redux DevTools extension support

Production Build

Generate optimized static files for deployment:

npm run build

Output:

• Bundles placed in /dist directory
• Hashed filenames for cache busting (e.g., main.[contenthash].js)
• Extracted CSS files with hashing
• Minified HTML, JS, and CSS
• Source maps generated

Reviewing the Example App

The starter includes a working Fuel Savings calculator app. Review the structure under /src before deleting example files to create your own app.

Deployment

Static Hosting

The /dist folder contains static files suitable for any static host:

Recommended Platforms:

• Netlify: Drag and drop /dist folder or connect git repo with build command npm run build and publish directory dist
• Vercel: Configure build command as npm run build and output directory as dist
• GitHub Pages: Push /dist contents to gh-pages branch
• AWS S3: Upload /dist contents to S3 bucket with static website hosting enabled
• Surge: surge dist

SPA Configuration

Since this uses React Router (connected-react-router), configure your server to serve index.html for all routes:

• Nginx: try_files $uri /index.html;
• Apache: FallbackResource /index.html
• Netlify/Vercel: Create _redirects file with /* /index.html 200

Environment Checklist Before Deploy

• Run npm run build locally to verify no errors
• Verify NODE_ENV is not set to production in your build environment (unless doing a production build)
• Ensure /dist contains index.html, hashed JS/CSS files, and assets

Troubleshooting

Installation Issues

File Watching / Hot Reload Failures

Build Errors

Runtime Issues

Post-Setup Cleanup

After reviewing the example app, delete example files:

• Remove Fuel Savings components from /src/components
• Update /src/reducers/index.js to remove fuel savings reducer
• Update /src/index.js to render your root component instead of example app