How Can I Use to Combine Django with Next.js

My earlier projects used Django with a traditional React setup, I built React, grabbed the index.html file from the static build, and served it through Django. However, as I explored SSR benefits for better SEO and performance, I discovered that Next.js was the perfect upgrade. Unlike static React builds, Next.js is designed to dynamically generate HTML on each request, which means serving a static HTML file (like React’s index.html) isn’t an option.

This integration forced me to rethink my architecture. Instead of a single monolithic service, I now have separate services (or processes) that communicate via a reverse proxy. This setup not only leverages the full power of SSR but also maintains Django’s role as a robust API backend.

The Two Approaches for Django & Next.js Integration

There are two main methods to integrate Django with Next.js, particularly when SSR is a requirement:

Separate Services with a Reverse Proxy

In this approach, Django and Next.js run as separate services, and a tool like Nginx routes the requests appropriately. The client’s search-related requests are sent to the Next.js server, while API calls go to Django.

Architecture Diagram (Mermaid):

graph TD
    Client -->|/search/*| Nginx
    Client -->|Other URLs| Nginx
    Nginx -->|/search/*| NextJS[Next.js Server]
    Nginx -->|API requests| Django
    NextJS -->|API calls| Django

Next.js Setup (pages/search/index.js):

async function getServerSideProps(context) {
  // Fetch data from Django API during SSR
  const res = await fetch('http://django-api:8000/api/search/');
  const data = await res.json();
  return { props: { data } };
}

export default function SearchPage({ data }) {
  return <div>{/* Render search results using the fetched data */}</div>;
}

Django API View (views.py):

rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view(['GET'])
def search_api(request):
    try:
        # Imagine perform_search is a function that processes the search query
        results = perform_search(request.query_params)
        return Response({'results': results})
    except Exception as e:
        return Response({'error': str(e)}, status=500)

Nginx Configuration:

{
    listen 80;
    
    location /search/ {
        proxy_pass http://nextjs:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/ {
        proxy_pass http://django:8000;
        proxy_set_header Host $host;
    }

    location / {
        proxy_pass http://django:8000;
    }
}

This configuration clearly separates the SSR responsibilities from the API backend, enabling each service to excel in its domain.

Direct Django-Next.js Integration

For development convenience, you might prefer integrating Next.js directly via Django. This approach essentially proxies Next.js requests through Django when both servers run on your local machine.

Django View as a Proxy (views.py):

requests
from django.http import HttpResponse
from django.views import View

class NextJSProxyView(View):
    NEXTJS_SERVER = 'http://localhost:3000'

    def get(self, request, *args, **kwargs):
        try:
            resp = requests.get(
                f"{self.NEXTJS_SERVER}{request.path}",
                headers=dict(request.headers),
                params=request.GET
            )
            return HttpResponse(resp.content, status=resp.status_code)
        except requests.exceptions.ConnectionError:
            return HttpResponse(
                "Next.js server not running", 
                status=503,
                content_type='text/plain'
            )

This view proxies the request to the Next.js server and returns its content—ideal for development but not recommended in production.

Enhancing Error Handling & Advanced Features

Custom Error Pages in Next.js

For a smoother user experience, I customized error pages in Next.js. When something goes wrong, the user sees a friendly error message rather than a cryptic server error.

Custom Error Component (pages/_error.js):

default function Error({ statusCode }) {
  return (
    <div>
      {statusCode 
        ? `Server error: ${statusCode}` 
        : 'Client error'}
    </div>
  );
}

Standardizing API Error Responses in Django

To maintain consistency, I created a helper function in Django that standardizes API responses, including errors.

Helper Function (utils.py):

rest_framework.response import Response

def api_response(data=None, status=200, error=None):
    return Response({
        'status': 'error' if error else 'success',
        'data': data,
        'error': error
    }, status=status)

Authentication & Shared Validation

I extended the integration to include features such as authentication and shared validation. On the Next.js side, you can use cookies to authenticate API calls:

Authentication Example (Next.js page):

Cookies from 'cookies';

export async function getServerSideProps({ req }) {
  const cookies = new Cookies(req.headers.cookie);
  const response = await fetch('/api/user/', {
    headers: { 
      'Authorization': `Bearer ${cookies.get('access_token')}`
    }
  });
  // ... handle response
}

For shared validation, I use Pydantic in Python and TypeScript interfaces in Next.js to ensure both sides adhere to the same data structure:

Python Validation (shared/validation.py):

pydantic import BaseModel

class SearchSchema(BaseModel):
    query: str
    max_results: int = 10

TypeScript Validation (shared/validation.ts):

interface SearchSchema {
  query: string;
  maxResults?: number;
}

Deployment Setup with Docker Compose

I built the deployment stack using Docker Compose for a straightforward setup:

Docker Compose File (docker-compose.yml):

: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - django
      - nextjs

  django:
    build: ./django-app
    command: gunicorn config.wsgi:application --bind 0.0.0.0:8000
    volumes:
      - ./django-app:/app
    environment:
      - DJANGO_ENV=production

  nextjs:
    build: ./next-app
    command: npm run start
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production

This configuration encapsulates the entire architecture, making deployment manageable and scalable.

Final Thoughts

Integrating Django with Next.js for SSR has been an enlightening challenge for me. It pushed me to rethink traditional monolithic architectures and embrace a more modular approach with separate services communicating through reverse proxies. This not only enhances the performance and SEO benefits of SSR with Next.js but also preserves Django’s role as a powerful API backend.

While the static export method worked well for a purely React-based approach, this new integration strategy opens the door for more dynamic content delivery and improves the overall user experience. I’ve learned that having a robust error handling mechanism, clear API response structures, and shared code for validations makes the system more maintainable and scalable.