1. If deploying to GitHub, ensure there is a "homepage" entry in package.json for where you are hosting it in Github.

   Examples:

   User Page

   "homepage": "https://amodhakal.github.io",
   

   Project Page

   "homepage": "https://amodhakal.github.io/portfolio",
   

   Custom Domain Page

   "homepage": "https://amodhakal.com",
   

   Vite: add the project directory as the base.

   vite.config.js

   export default {
     ...
     base: "/portfolio"
   };
   

2. Switch to the HashRouter since GitHub pages doesn't support the tech used by the BrowserRouter.

   index

   import React from 'react';
   import ReactDOM from 'react-dom/client';
   import { HashRouter } from 'react-router-dom'; // Note 1
   import App from './App';
   import './styles/index.css';
   
   ReactDOM.createRoot(document.getElementById('root')).render(
     <React.StrictMode>
       <HashRouter>
         <App />
       </HashRouter>
     </React.StrictMode>
   );
   

   react-router data routers

   import ReactDOM from 'react-dom/client';
   import App from './App';
   
   ReactDOM.createRoot(document.getElementById('root')).render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
   );
   

   import {
     createHashRouter,
     RouterProvider
   } from 'react-router-dom'; // Note 1
   // import routed components
   
   const router = createHashRouter([
     ... routes configuration
   ]);
   
   const App = () => {
     ...
   
     return <RouterProvider router={router} />;
   };
   
   export default App;
   

For more details see the create-react-app docs for deploying to GitHub Pages and notes on client-side routing.

¹If using React-Router 7 library, all exports are from react-router instead of react-router-dom. Follow the RR7 installation and setup.

As per deployment docs at https://create-react-app.dev/, for GH pages:

GitHub Pages doesn’t support routers that use the HTML5 pushState history API under the hood (for example, React Router using browserHistory). This is because when there is a fresh page load for a url like http://user.github.io/todomvc/todos/42, where /todos/42 is a frontend route, the GitHub Pages server returns 404 because it knows nothing of /todos/42.

If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions:

• You could switch from using HTML5 history API to routing with hashes. If you use React Router, you can switch to hashHistory for this effect, but the URL will be longer and more verbose (for example, http://user.github.io/todomvc/#/todos/42?_k=yknaj) Read more about different history implementations of react-router.

Change your routing from:

    <BrowserRouter basename={process.env.PUBLIC_URL}>
      <Route render = {({ location }) => (
         <Layout location = { location }>
             <Switch location = { location }>
                <Route exact path = '/' component = { Home } />
                <Route exact path = '/buttons/' component = { Buttons } />
                <Route component = { NotFound }/>
              </Switch>
           </Layout>
       )} />
    </BrowserRouter>

To:

import { HashRouter, Route, Link } from "react-router-dom";

...


    <HashRouter basename={process.env.PUBLIC_URL}>
      <Route render = {({ location }) => (
         <Layout location = { location }>
             <Switch location = { location }>
                <Route exact path = '/' component = { Home } />
                <Route exact path = '/buttons/' component = { Buttons } />
                <Route component = { NotFound }/>
              </Switch>
           </Layout>
       )} />
    </HashRouter>
...

• Alternatively, you can use a trick to teach GitHub Pages to handle 404 by redirecting to your index.html page with a special redirect parameter. You would need to add a 404.html file with the redirection code to the build folder before deploying your project, and you’ll need to add code handling the redirect parameter to index.html. You can find a detailed explanation of this technique in this guide.

///install git hubpages
$ npm install --save gh-pages

//Add some properties to the app’s package.json file. At the ***top level, add a homepage property. Define its value to be the string http://{username}.github.io/{repo-name}, where {username} is your GitHub username, and {repo-name} is the name of the GitHub repository (my-app) you created in step 3.

//expmle
"homepage": "http://.github.io/",

//in scripts
"scripts": {
//...
"predeploy": "npm run build",
"deploy": "gh-pages -d build",
//...
"build": "react-scripts build && cp build/index.html build/404.html", // this will prevent page reloads to give a 404 error
}

// ??? if you are using the Router from react-router-dom then you need to change the Browser router tags to

// u need to wrap the base name in `` for some reason that doesn't work here
< BrowserRouter basename={ /${process.env.PUBLIC_URL}}>
< app/>
< /BrowserRouter>

/// + in the Routes path="/" need to be path=""
< Routes>
< Route path="" element={} />
< /Routes>

**** add the url in the README.md file
// 1. add the changes
$ npm add .
// 2. commit the changes
$ npm commit -m master

// 3. then push the origin
$ npm push origin

/// 4.Last deploy it
$ npm run deploy

For anyone else stuck on the issue, I had bundled all my files using parcel bundler so the index.html in dist folder was being served instead of the index.html in root folder. Using gh-pages to set dist as root folder worked for me.

Refer the commands in https://stackoverflow.com/a/42501045/11566161 Courtesy: Shri Hari L in comments.