GitHub Pages is a free hosting service provided by GitHub that allows developers to publish static websites directly from their repositories. It’s widely used for personal projects, documentation, and portfolio sites. Since React apps, when built, generate static files (HTML, CSS, and JavaScript), GitHub Pages is an excellent option for hosting them without the need for a dedicated server.
While both Create React App (CRA) and Vite can be deployed to GitHub Pages, the setup differs slightly because of the way they handle builds and static files.
Which One Should You Use?
If you're starting a new project, Vite is recommended because it's faster and more efficient.
If you’re working with an existing Create React App, just follow the CRA steps below.
Both methods get your React app live on GitHub Pages, so pick the one that best fits your workflow!
So let's take a look at both steps.
Deploying Create React App (CRA) to GitHub Pages
CRA generates a single-page application (SPA) that requires additional configuration to work on GitHub Pages.
Key Differences for CRA:
- Needs the gh-pages package.
- Requires a homepage field in package.json to avoid routing issues.
- Uses npm run build before deployment.
First create a new repository in your github account and make sure your terminal is sync with your github account.
To sync your terminal with GitHub for easy pushing, you need to set up SSH authentication or use HTTPS with saved credentials. With SSH authentication, you no longer need to enter passwords when pushing to GitHub. Just git push, and your changes are live!
Steps for CRA Deployment:
Install gh-pages
npm install gh-pages --save-dev
Add a homepage field in package.
"homepage": "https://your-username.github.io/repository-name"
Add deployment scripts:
"predeploy": "npm run build",
"deploy": "gh-pages -d build"
Deploy using
npm run deploy
Finally you can view your new published site using the link you provide in the package.json
"homepage": ["https://your-username.github.io/repository-name"](https://your-username.github.io/repository-name)
ℹ️ Issue with CRA: Since GitHub Pages serves static files, it doesn't support direct client-side routing (e.g., React Router). You may need a .htaccess file or redirect workaround.
Deploying Vite React App to GitHub Pages
Vite is faster and more optimized than CRA but requires slight modifications for GitHub Pages.
Key Differences for Vite:
- Uses vite.config.js to set the base URL.
- Doesn't require gh-pages, but it's commonly used.
- Supports faster builds compared to CRA.
Steps for Vite Deployment:
Install gh-pages
npm install gh-pages --save-dev
Update vite.config.js (if not created, make one):
- Unlike CRA, Vite needs base: '/repository-name/' in vite.config.js so GitHub Pages knows where to find the static files.
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
base: '/repository-name/' // Set the base path for GitHub Pages
});
Add deployment scripts in package.json
"predeploy": "npm run build",
"deploy": "gh-pages -d dist"
Deploy using:
npm run deploy
Finally you can view your new published site using the link you provide in the package.json
"homepage": ["https://your-username.github.io/repository-name"](https://your-username.github.io/repository-name)
In summary, When deploying a React app to GitHub Pages, there are key differences between Create React App (CRA) and Vite. CRA generates a /build folder, while Vite creates a /dist folder. In CRA, you must set a homepage field in package.json, whereas Vite requires configuring the base path in vite.config.js. Both setups commonly use the gh-pages package for deployment. However, CRA may face routing issues that require additional workarounds, while Vite handles this more smoothly with its base configuration. Additionally, Vite offers significantly faster build times due to its optimized ES module-based approach, making it a better choice for new projects.
Top comments (0)