django-nextjs

To ensure a stable integration, follow these requirements:

• Public Files: Place Next.js public files in the public/next subdirectory.
• Middleware: Ensure all your Django middlewares are async-capable.
• URL Configuration: Set APPEND_SLASH = False in your Django settings.py to prevent redirect loops. Do not add trailing slashes to your Next.js paths in urls.py.
• Data Flow: Use an API (like Django REST Framework or GraphQL) to pass data between Django and Next.js.
• Server Management: This package does not start the Next.js server; you must run npm run dev or npm run start separately.

To integrate Next.js with Django, install the package via pip and add django_nextjs to your INSTALLED_APPS in Django settings.

Note: You must use an ASGI server (like Daphne or Uvicorn) and configure your asgi.py with NextJsMiddleware to support Next.js features like fast refresh.

pip install django-nextjs

INSTALLED_APPS = [
    ...
    "django_nextjs",
]

Wrap your Django ASGI application with NextJsMiddleware. This middleware handles routing for Next.js assets and API requests, and supports WebSockets for fast refresh.

If you are using Django Channels, you can wrap a ProtocolTypeRouter instead.

import os
from django.core.asgi import get_asgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
django_asgi_app = get_asgi_application()

from django_nextjs.asgi import NextJsMiddleware

application = NextJsMiddleware(django_asgi_app)

With Django Channels:

application = NextJsMiddleware(
    ProtocolTypeRouter(
        {
            "http": django_asgi_app,
            "websocket": my_websocket_handler,
            # ...
        }
    )
)

In production, you can optimize performance by serving the /_next/static directory directly via Nginx. This avoids routing static asset requests through the Django application server.

# Replace NEXTJS_PATH with the actual path to your Next.js project
location /_next/static/ {
    alias NEXTJS_PATH/.next/static/;
    add_header Cache-Control "public, max-age=31536000, immutable";
}

To contribute to django-nextjs, install the development dependencies and set up the pre-commit hooks using the following commands:

pip install -e '.[dev]'
pre-commit install

Configure django-nextjs by defining the NEXTJS_SETTINGS dictionary in your Django settings file. This allows you to specify the Next.js server URL, CSRF token handling, and the public subdirectory path.

NEXTJS_SETTINGS = {
    "nextjs_server_url": "http://127.0.0.1:3000",
    "ensure_csrf_token": True,
    "public_subdirectory": "/next",
}

Use the nextjs_page view to map Django URL paths to Next.js pages.

If you are using the Next.js App Router, it is highly recommended to set stream=True to enable HTML streaming, which allows for instant loading states.

from django_nextjs.views import nextjs_page

urlpatterns = [
    path("/my/page", nextjs_page(), name="my_page"),

    # With App Router streaming (recommended)
    path("/other/page", nextjs_page(stream=True), name="other_page"),
]

The following keys are available within the NEXTJS_SETTINGS dictionary:

• nextjs_server_url: The URL of the Next.js server (typically started via npm run dev or npm run start).
• ensure_csrf_token: A boolean. If True, Django ensures a CSRF token is generated and included in the initial request to the Next.js server using django.middleware.csrf.get_token. This is useful for preventing GraphQL POST request failures in getServerSideProps when a user's first request lacks a CSRF cookie.
• public_subdirectory: A string defining a custom path for the Next.js public directory (defaults to /next). If changed, you must update your production reverse proxy configuration to match.

NEXTJS_SETTINGS = {
    "nextjs_server_url": "string",
    "ensure_csrf_token": bool,
    "public_subdirectory": "string",
}