Step-by-Step Guide for Deploying a Next.js Project as GitHub Pages

Deploying a Next.js project to GitHub Pages can be quite challenging, especially if you follow various methods that may not work as expected. After struggling with numerous approaches and configurations, I finally found a solution that works seamlessly. This guide will walk you through the process step-by-step, ensuring you can successfully deploy your Next.js application.

Important Note: Creating Your Repository

Before we begin, it's essential to create a repository on GitHub specifically for your project. For deploying a user site on GitHub Pages, you need to name your repository in the following format:

<your-github-username>.github.io

For example, if your GitHub username is LovelyDev829, your repository should be named as LovelyDev829.github.io. This naming convention is crucial as it allows GitHub to recognize it as a user site and serve it correctly.

Initial Setup: package.json Configuration

Before we dive into the deployment process, let's set up the package.json file correctly. This file is essential for managing scripts that facilitate the development, building, and deployment of your Next.js application.
Here’s how your package.json should look:

{
  "name": "LovelyDev829-github-page",
  "version": "1.0.0",
  "homepage": "https://LovelyDev829.github.io",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "export": "next export",
    "start": "next start",
    "deploy": "gh-pages -d out --dotfiles"
  },
  "dependencies": {
    ...
  }
}

• homepage: Set this to your GitHub Pages URL. This ensures that paths are correctly resolved when your app is built and deployed.
• dev: Starts the Next.js development server.
• build: Builds the application and exports it as static files.
• start: Starts the Next.js production server.
• deploy: Deploys the contents of the out directory to GitHub Pages, including dotfiles like .nojekyll.

Step 1: Build Your Project

Before deploying, you need to prepare your Next.js application for static export. This involves building the project and generating the necessary files.
Run the Build Command:
Open your terminal and navigate to your project directory. Execute the following command:

npm run build

Export the Project:
After building, export your project to create a static version:

npm run export

This command will generate an out folder containing all the static files required for deployment.

Step 2: Create the .nojekyll File

To prevent GitHub Pages from processing your files through Jekyll (which can ignore files starting with an underscore), you need to create a .nojekyll file in the out folder.
Create the File:
Run the following command in your terminal:

touch out/.nojekyll

Note: The .nojekyll file should be empty; there’s no need to write anything inside it.

If touch is not recognized, you can do:

npm install -g touch-cli

Step 3: Deploy Your Application

Now that everything is set up, it's time to deploy your application to GitHub Pages.
Run the Deployment Command:
Execute the following command in your terminal:

npm run deploy

This command will push the contents of the out directory to the gh-pages branch of your repository.

Step 4: Configure GitHub Settings

After deploying, you need to configure GitHub Pages settings for your repository:

1. Go to Your Repository on GitHub: Navigate to your repository on GitHub.
2. Access Settings: Click on the "Settings" tab.
3. Configure Pages: Scroll down to the "Pages" section. Under "Source," select the gh-pages branch as your deployment source and save changes.

Step 5: Verify Your Deployment

Once you've completed all previous steps, it's important to check that your application is live and functioning correctly:

1. Check Your Site URL: Go to https://<your-github-username>.github.io. Replace <your-github-username> with your actual GitHub username. In this case, https://LovelyDev829.github.io
2. Verify Functionality: Open your browser and navigate to this URL. Ensure that all pages load correctly and that styles are applied as expected.
3. Inspect Console for Errors: Use your browser's developer tools (usually accessible by pressing F12) to check for any console errors or issues loading resources.

Simplification

As you set your package.json like follows:

{
  "name": "LovelyDev829-github-page",
  "version": "1.0.0",
  "homepage": "https://LovelyDev829.github.io",
  "scripts": {
    "dev": "next dev",
    "build": "next build && next export",
    "start": "next start",
    "predeploy": "touch out/.nojekyll",
    "deploy": "gh-pages -d out --dotfiles"
  },
  "dependencies": {
    ...
  }
}

• predeploy: Runs before "deploy" automatically. You can build, export and deploy by just:

npm run build
npm run deploy

Conclusion

By following these steps, you should now have a fully functional Next.js application deployed on GitHub Pages. If you encounter any issues, double-check each step, especially ensuring that the .nojekyll file is present and that you are using the correct deployment commands.

Check the Repository and Live link.
Star Repository and Follow me on Github