Proper Configuration for Deploying React Applications

When deploying a React application, forgetting to set the homepage property in package.json can lead to broken asset paths and routing issues, especially when not deploying to the root domain.

The Problem: Missing Homepage Configuration

// ❌ Problematic package.json (missing homepage)
{
  "name": "my-app",
  "version": "0.1.0",
  "private": true
}

Solutions for Different Deployment Scenarios

1. Deploying to Root Domain (e.g., yourdomain.com)

// ✅ Recommended for root domain deployment
{
  "homepage": "https://yourdomain.com"
}

2. Deploying to Subdirectory (e.g., yourdomain.com/app)

// ✅ For subdirectory deployment
{
  "homepage": "https://yourdomain.com/app"
}

3. Deploying to GitHub Pages

// ✅ GitHub Pages configuration
{
  "homepage": "https://username.github.io/repo-name"
}

4. Dynamic Configuration (Using Environment Variables)

// ✅ Flexible configuration
{
  "homepage": ".",
}

Then set the public URL when building:

PUBLIC_URL=/my-app npm run build

Additional Required Configuration

For React Router (if using)

// In your router configuration
<BrowserRouter basename={process.env.PUBLIC_URL}>
  <App />
</BrowserRouter>

For Create React App

Create React App automatically handles the homepage field by:

Setting correct paths in the built HTML files
Adjusting the asset paths in the generated CSS/JS

Verification Steps

After setting the homepage property:

Build your application:

   npm run build

Check the generated index.html in the build folder:

   <!-- Should show correct paths -->
   <link href="/app/static/css/main.css" rel="stylesheet">

Test locally before deploying:

   serve -s build

Common Deployment Issues Without Homepage

Broken asset paths – CSS/JS files not loading
Incorrect routing – Links and redirects failing
Blank pages – When refreshing on subroutes
404 errors – For client-side routed pages

Best Practices

Always set the homepage before building for deployment
Use environment variables for different deployment targets
Test locally using serve or similar tools
Update your build scripts if using custom deployment
Document your deployment requirements in README.md

// Example complete package.json
{
  "name": "my-app",
  "version": "0.1.0",
  "private": true,
  "homepage": "https://yourdomain.com/app",
  "scripts": {
    "build": "react-scripts build",
    "deploy": "npm run build && gh-pages -d build"
  }
}

Remember that proper homepage configuration ensures all your application assets load correctly regardless of where you deploy it. This is especially crucial when not deploying to the root domain of your server.

Deploying React app without homepage in package.json