How to Return JSON in Next.js not-found.tsx?

ONLINECAST

2 min read

·

04-10-2024

10

0

Share

Returning JSON in Next.js not-found.tsx: A Simple Guide

When building web applications using Next.js, it's crucial to handle error scenarios gracefully, including handling 404 Not Found errors. Returning a JSON response instead of a default HTML page can be useful for scenarios like API integrations or providing consistent error responses to frontend applications.

This article will guide you through returning JSON in your not-found.tsx file in Next.js, ensuring a smooth and efficient user experience.

The Problem: Returning JSON from 404 Pages

Traditionally, Next.js's not-found.tsx component renders a standard HTML page when a route is not found. However, in certain scenarios, you might want to return a structured JSON response, particularly when interacting with APIs or for frontend applications expecting specific error data.

The Solution: Utilizing getServerSideProps

Let's examine a practical approach to returning JSON in not-found.tsx.

// pages/api/not-found.js
export default async function handler(req, res) {
  res.status(404).json({
    message: 'Resource not found',
    status: 'error',
  });
}

// pages/not-found.tsx
import { GetServerSideProps } from 'next';

export const getServerSideProps: GetServerSideProps = async (context) => {
  return {
    props: {
      // Example JSON data for 404 page
      notFoundMessage: 'Page not found',
    },
  };
};

export default function NotFoundPage({ notFoundMessage }) {
  return (
    <div>
      <h1>{notFoundMessage}</h1>
    </div>
  );
}

Explanation:

1. API Route: We start by creating an API route (pages/api/not-found.js) that directly handles the 404 response. This route returns a JSON object with a message and error status.

2. getServerSideProps: The not-found.tsx component utilizes getServerSideProps to fetch data on the server before rendering the component. In this case, it fetches the JSON data from our API route (/api/not-found) and passes it to the component's props.

3. Component Rendering: The component receives the notFoundMessage prop from getServerSideProps and renders it dynamically.

Key Points:

• Data Consistency: By utilizing getServerSideProps, we ensure data consistency across the entire application, preventing unexpected rendering issues when returning JSON.
• Error Handling: The API route allows you to structure error responses consistently, providing a reliable mechanism for handling 404 errors.
• Flexibility: This approach allows you to tailor the JSON response based on the specific requirements of your application, providing flexibility for different error scenarios.

Additional Considerations

• Error Page Customization: You can further customize the not-found.tsx component to handle various 404 scenarios, displaying different messages or redirecting to specific pages.
• External API Integration: Instead of using an internal API route, you can fetch data from external APIs within getServerSideProps to handle specific 404 scenarios based on API responses.
• Dynamic Messages: You can dynamically modify the error messages based on specific routes or error types using the context object provided within getServerSideProps.

Conclusion

Returning JSON responses in Next.js's not-found.tsx provides a robust and versatile approach to handling 404 Not Found errors. Utilizing getServerSideProps and API routes enables you to maintain data consistency, structure error responses, and enhance your application's error handling capabilities.