Codakey
Play
← Back to facebookincubator/create-react-app

How to Deploy & Use facebookincubator/create-react-app

# Create React App Deployment & Usage Guide

> **Deprecation Notice**: Create React App is in long-term stasis as of 2024. The React team recommends using modern frameworks (Next.js, Remix, etc.) for new production applications. This guide is maintained for existing projects and maintenance contexts.

## Prerequisites

- **Node.js**: Version 14.0.0 or later (Latest LTS recommended)
- **Package Manager**: npm 5.2+ (includes npx), Yarn 0.25+, or npm 6+ (for `npm init`)
- **OS**: macOS, Windows, or Linux
- **Optional**: nvm (Node Version Manager) for managing Node versions across projects

**Verify installation:**
```bash
node -v
npm -v

Installation

Create React App requires no global installation. Use one of the following methods to scaffold a new project:

Using npx (recommended):

npx create-react-app my-app

Using npm:

npm init react-app my-app

Using Yarn:

yarn create react-app my-app

Post-installation:

cd my-app

The command creates the following structure:

my-app/
├── node_modules/
├── public/
│   ├── favicon.ico
│   ├── index.html
│   └── manifest.json
├── src/
│   ├── App.css
│   ├── App.js
│   ├── App.test.js
│   ├── index.css
│   ├── index.js
│   ├── logo.svg
│   ├── serviceWorker.js
│   └── setupTests.js
├── .gitignore
├── package.json
└── README.md

Important: If you previously installed create-react-app globally, remove it to ensure npx uses the latest version:

npm uninstall -g create-react-app
# or
yarn global remove create-react-app

Configuration

Create React App requires zero configuration for basic operation. Webpack, Babel, and ESLint are preconfigured and hidden.

Environment Variables

Create a .env file in the project root for environment-specific variables:

# .env
REACT_APP_API_URL=https://api.example.com
REACT_APP_FEATURE_FLAG=true

Rules:

  • Variables must begin with REACT_APP_ to be accessible in the application
  • Access via process.env.REACT_APP_API_URL
  • NODE_ENV is automatically set to development, test, or production

TypeScript Support

To initialize with TypeScript:

npx create-react-app my-app --template typescript

Advanced Configuration (Ejecting)

Warning: Irreversible operation. Exposes all configuration files.

npm run eject

This reveals webpack configs, Babel presets, and ESLint configurations in the config/ and scripts/ directories.

Build & Run

Development Mode

Start the development server with hot reloading:

npm start
# or
yarn start
  • Opens at http://localhost:3000 (auto-detects if port 3000 is occupied)
  • Supports LAN testing via local network IP (displayed in terminal)
  • Live reload on file changes
  • Error overlay in browser for compilation errors

Testing

Run the interactive test watcher:

npm test
# or
yarn test
  • Runs Jest in watch mode by default
  • Tests related to changed files run automatically
  • Press a to run all tests, q to quit

Production Build

Create an optimized production bundle:

npm run build
# or
yarn build

Output:

  • Generates build/ directory with minified, hashed assets
  • Includes source maps (configurable via GENERATE_SOURCEMAP=false)
  • Ready for static hosting

Environment-specific builds:

# Disable source maps
GENERATE_SOURCEMAP=false npm run build

# Analyze bundle size
npm run build -- --stats

Deployment

The build/ folder contains static assets suitable for any static hosting provider.

Static Hosting Providers

Netlify:

npm run build
# Drag and drop the build folder, or use Netlify CLI
npx netlify deploy --dir=build --prod

Vercel:

npx vercel --prod
# Ensure vercel.json configures SPA routing if using client-side routing

GitHub Pages:

  1. Add to package.json:
"homepage": "https://username.github.io/repo-name"
  1. Install gh-pages:
npm install --save-dev gh-pages
  1. Add scripts:
"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}
  1. Deploy:
npm run deploy

AWS S3 / CloudFront: Upload contents of build/ to S3 bucket configured for static website hosting. Enable SPA routing by setting error document to index.html.

Server Requirements

  • Static hosting only: No Node.js server required
  • Client-side routing: Configure server to serve index.html for 404s (SPA fallback)
  • HTTPS: Recommended for service workers (PWA features)

Troubleshooting

Port Conflicts

If port 3000 is in use, the dev server automatically prompts to use the next available port:

? Something is already running on port 3000. Probably:
  /path/to/node (PID 12345)
  in /path/to/project

Would you like to run the app on another port instead? (Y/n)

Global Installation Errors

Symptom: Old version being used or permission errors.

Solution:

npm uninstall -g create-react-app
npx create-react-app --version  # Verify latest

Environment Variables Not Loading

Symptom: process.env.REACT_APP_VAR returns undefined.

Checks:

  • Variable must start with REACT_APP_
  • Restart dev server after modifying .env
  • Variables are embedded at build time; changes require rebuild

TypeScript Compilation Errors

Symptom: Build fails on TypeScript errors.

Workaround (not recommended for CI):

TSC_COMPILE_ON_ERROR=true npm start

This allows development to continue despite type errors (shows warnings instead).

Out of Memory During Build

Symptom: JavaScript heap out of memory on large projects.

Solution:

# Increase Node memory limit
node --max-old-space-size=4096 node_modules/.bin/react-scripts build

Editor Integration

The dev server automatically detects running editors for error click-through. Supported editors include VS Code, Atom, Sublime Text, and Vim/Emacs (terminal). Set via REACT_EDITOR environment variable if detection fails:

REACT_EDITOR=code npm start
← Project overviewView alternatives to facebookincubator/create-react-app →