Forgetting to set homepage in package.json for static hosting

When deploying React applications to static hosts (like GitHub Pages, Netlify, or Vercel), forgetting to set the homepage field in package.json can cause several issues with asset paths and routing.

Why It Matters

1. Broken asset paths – CSS, JS, and image files won’t load properly
2. Routing failures – Client-side routing breaks when not at root domain
3. 404 errors – Page refreshes on sub-routes fail to resolve
4. Incorrect base URLs – API requests and links may point to wrong locations

How to Configure Properly

1. For Root Domain Deployments

{
  "name": "my-app",
  "homepage": "https://yourdomain.com",
  // or for GitHub Pages user sites:
  "homepage": "https://username.github.io"
}

2. For Project Pages (GitHub Pages)

{
  "homepage": "https://username.github.io/repository-name",
  // Also add this for Create React App:
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}

3. For Subdirectory Deployments

{
  "homepage": "https://yourdomain.com/subdirectory",
  // This affects all asset paths
}

Framework-Specific Solutions

Create React App

CRA automatically uses the homepage field to:

• Set the PUBLIC_URL during build
• Generate correct asset paths
• Configure the router basename (if using react-router)

Next.js

Next.js handles this differently:

{
  "next": {
    "basePath": "/subdirectory"  // For subdirectory deployments
  }
}

Or configure in next.config.js:

module.exports = {
  basePath: '/subdirectory',
  assetPrefix: '/subdirectory/'
}

Vite

Configure in vite.config.js:

export default defineConfig({
  base: '/subdirectory/'
})

Common Problems and Fixes

1. Assets 404 After Deployment

Symptom: CSS/JS files not loading
Fix: Set correct homepage and rebuild

2. Routing Works But Refresh Fails

Symptom: Routes work but page refresh shows 404
Fix: Configure both homepage and your static host’s redirect rules

3. Mixed Content Warnings

Symptom: HTTPS site trying to load HTTP assets
Fix: Ensure homepage uses HTTPS protocol

Deployment Checklist

1. Verify homepage in package.json matches deployment URL
2. For Create React App, test with serve -s build locally
3. For GitHub Pages:

   npm install --save-dev gh-pages
   npm run deploy

4. For Netlify/Vercel:

• Set “Base directory” to match package.json homepage
• Configure redirects for client-side routing

Advanced Configuration

Environment Variables

For dynamic environments:

{
  "homepage": ".",
  "scripts": {
    "build": "PUBLIC_URL=$DEPLOY_URL react-scripts build"
  }
}

Custom Webpack Config

If not using CRA, configure webpack:

output: {
  publicPath: process.env.PUBLIC_URL || '/'
}

By properly setting the homepage field and understanding how it affects your build process, you’ll avoid common static hosting issues and ensure your application loads correctly in all environments.