Direct Access Routes in Next.js Return 404, but Work Fine in Development Environment

Question

Problem:

• In a Next.js application hosted on Azure App Service, accessing routes directly (e.g., /vehicle-details) results in a 404 Not Found error.
• However, navigating to these same routes via internal navigation (Link or router.push) works perfectly.
• In the development environment, everything functions as expected, and direct routes load without issues.
• The issue only appears in the production environment on Azure.

---

Technical Details:

• Next.js Rendering Method: Client-Side Rendering (CSR).
• Hosting Environment: Azure App Service.

---

Next.config.js:

const path = require('path');

/** @type {import('next').NextConfig} */
const withTM = require('next-transpile-modules')([
  '@fullcalendar/common',
  '@fullcalendar/react',
  '@fullcalendar/daygrid',
  '@fullcalendar/list',
  '@fullcalendar/timegrid'
]);

module.exports = withTM({
  distDir: '.next',
  output: 'standalone',
  trailingSlash: false,
  reactStrictMode: false,
  webpack: (config, { isServer }) => {
    if (config.watchOptions) {
      config.watchOptions.ignored = '**/node_modules/**';
    }

    config.resolve.alias = {
      ...config.resolve.alias,
      apexcharts: path.resolve(__dirname, './node_modules/apexcharts-clevision')
    };

    if (!isServer) {
      config.output.publicPath = '/_next/';
    }

    return config;
  },
  typescript: {
    ignoreBuildErrors: true
  },
  eslint: {
    ignoreDuringBuilds: true
  }
})

Question:

Is there a specific configuration in Azure App Service required to handle direct access routes (Deep Links) in Next.js properly? Are there any known best practices or additional configurations needed to address this issue?

Answer 1

The 404 errors on direct routes in a Next.js app on Azure occur because the server can't find the route, which is due to Next.js using client-side routing.

If you are deploying to a Windows-based Azure Web App, you should use a web.config file.

<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="Next.js Routes" stopProcessing="true">
                    <match url=".*" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
                        <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="/" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

It is better to use a Linux-based Azure Web App as routing is handled smoothly.

I created a sample Next.js app with routing and deployed it to a Linux-based Azure Web App using GitHub Actions.

Make sure the .next directory is deployed correctly.

Workflow File:

name: Build and deploy Node.js app to Azure Web App - kawebpp
on:
  push:
    branches:
      - main
  workflow_dispatch:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js version
        uses: actions/setup-node@v3
        with:
          node-version: '18.x'
      - name: npm install, build, and test
        run: |
          npm install
          npm run build --if-present
          mv .next/static .next/standalone/.next/static
      - name: Zip artifact for deployment
        run: zip release.zip ./* .next -qr
      - name: Upload artifact for deployment job
        uses: actions/upload-artifact@v4
        with:
          name: node-app
          path: release.zip
  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: 'Production'
      url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}
    permissions:
      id-token: write 
    steps:
      - name: Download artifact from build job
        uses: actions/download-artifact@v4
        with:
          name: node-app
      - name: Unzip artifact for deployment
        run: unzip release.zip
      - name: Login to Azure
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZUREAPPSERVICE_CLIENTID_83B70739DF0945729AA4CE9A46AB125D }}
          tenant-id: ${{ secrets.AZUREAPPSERVICE_TENANTID_44362B3B45C842599F6DA4078616BA05 }}
          subscription-id: ${{ secrets.AZUREAPPSERVICE_SUBSCRIPTIONID_F17A1BFD2D1043D7A1622137667A64A5 }}
      - name: 'Deploy to Azure Web App'
        id: deploy-to-webapp
        uses: azure/webapps-deploy@v3
        with:
          app-name: 'kawebpp'
          slot-name: 'Production'
          package: .      

Add below Startup command to the configuration section of Azure Web App.

node .next/standalone/server.js

Azure Output: