DEV Community

Cover image for 6 steps to deploy your React Next.js app with Github pages
David
David

Posted on

6 steps to deploy your React Next.js app with Github pages

Deploying a Next.js app to GitHub Pages can be a bit tricky due to the static nature of GitHub Pages and the dynamic features of Next.js. In this article, I'll walk you through the steps to successfully deploy do it.

Prerequisites

  • A GitHub account
  • Node.js and npm installed on your machine
  • A Next.js project ready to deploy

Step 1: Install gh-pages

npm install gh-pages --save-dev

Step 2: Update next.config.mjs

Next, you need to update your next.config.js (or next.config.mjs) file to handle the base path and asset prefix correctly.

const isProd = process.env.NODE_ENV === 'production';
const nextConfig = {
  reactStrictMode: true,
  images: {
    unoptimized: true, // Disable default image optimization
  },
  assetPrefix: isProd ? '/your-repository-name/' : '',
  basePath: isProd ? '/your-repository-name' : '',
  output: 'export'
};

export default nextConfig;
Enter fullscreen mode Exit fullscreen mode

isProd checks if the NODE_ENV environment variable is set to 'production'. If it is, isProd will be true; otherwise, it will be false.
Conditional assetPrefix and basePath are set to your repository name only if isProd is true. Otherwise, they are set to an empty string for local development.
The images.unoptimized option is set to true to disable the default image optimization, which is not compatible with static exports.

Step 3: Update package.json

Update your package.json to include the homepage field and the deploy scripts.

"homepage": "https://<your-github-username>.github.io/<your-repo-name>",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d out"
  },
Enter fullscreen mode Exit fullscreen mode

Replace and with your GitHub username and repository name.

Step 4: Deploy Your App

Run npm run predeploy and npm run deploy

These commands will:

  • Build your project.
  • Export it to the out directory.
  • Deploy it to the gh-pages branch on GitHub. Push your work to your GitHub branch before the next step

Step 5: Configure GitHub Pages

Go to your repository on GitHub.
Navigate to Settings > Pages.
Under Source, select the gh-pages branch.
Save the settings.
Add manually the .nojekyll file at the root of the gh-pages branch on GitHub. Learn more about this here.

Step 6: Verify Deployment

After deploying, open your GitHub Pages URL (e.g., https://.github.io/) to verify that your app is live.

And voila!

Feel free to leave any questions or comments below. Happy coding!

Top comments (5)

Collapse
 
metoohard_69c220aec4653dd profile image
MEtooHARD

This helps!
struggled for deploying it to github pages
and this works!

Collapse
 
daviidy profile image
David

Glad to know it works. 🙂

Collapse
 
devakone profile image
Abou Kone

This is handy! I have the need to do just that! Thanks Dave!

Collapse
 
roxana_gheorghe_e7fa54867 profile image
Roxana Gheorghe

Hei, but how did you managed for the static assets?

Image description

Collapse
 
aashutoshkr profile image
Aashutosh Kumar

Update the deploy script form deploy": "gh-pages -d out" to "deploy": "gh-pages -d out --nojekyll" so that the assets under _next folder can be served.
Read this discussion: github.com/vercel/next.js/discussi... and try to build and deploy again.