# Django Next.js
[](https://pypi.python.org/pypi/django-nextjs/)
[](https://github.com/QueraTeam/django-nextjs/actions)
[](https://github.com/QueraTeam/django-nextjs/blob/master/LICENSE)
[](https://github.com/psf/black)
Next.js integration for Django projects.
So you want to use both Django and Next.js in your project. There are two scenarios:
1. You are starting a new project and you want to use Django as back-end and Next.js as front-end.
Django only serves API requests. All front-end code lives in Next.js and you don't write any Django template.
In this scenario you **don't need** this package (although you can use it).
You simply start both Django and Next.js servers and point your public webserver to Next.js.
2. You need both Django templates and Next.js at the same time and those pages should easily link to each other.
Maybe you have an existing Django project which has pages rendered by Django template
and want some new pages in Next.js.
Or you want to migrate your front-end to Next.js but since the project is large, you need to do it gradually.
In this scenario, **this package is for you!**
## How does it work?
From a [comment on StackOverflow]:
> Run 2 ports on the same server. One for django (public facing)
> and one for Next.js (internal).
> Let django handle all web requests.
> For each request, query Next.js from django view to get HTML response.
> Return that exact HTML response from django view.
## Installation
- Install the latest version from PyPI.
```shell
pip install django-nextjs
```
- Add `django_nextjs.apps.DjangoNextJSConfig` to `INSTALLED_APPS`.
- Set up Next.js URLs depending on your environment.
### Setup Next.js URLs (Development Environment)
If you're serving your site under ASGI during development,
use [Django Channels](https://channels.readthedocs.io/en/stable/) and
add `NextJSProxyHttpConsumer`, `NextJSProxyWebsocketConsumer` to `asgi.py` like the following example.
**Note:** We recommend using ASGI and Django Channels,
because it is required for [fast refresh](https://nextjs.org/docs/architecture/fast-refresh) (hot module replacement) to work properly in Nextjs 12+.
```python
import os
from django.core.asgi import get_asgi_application
from django.urls import re_path, path
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
django_asgi_app = get_asgi_application()
from channels.auth import AuthMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from django_nextjs.proxy import NextJSProxyHttpConsumer, NextJSProxyWebsocketConsumer
from django.conf import settings
# put your custom routes here if you need
http_routes = [re_path(r"", django_asgi_app)]
websocket_routers = []
if settings.DEBUG:
http_routes.insert(0, re_path(r"^(?:_next|__next|next).*", NextJSProxyHttpConsumer.as_asgi()))
websocket_routers.insert(0, path("_next/webpack-hmr", NextJSProxyWebsocketConsumer.as_asgi()))
application = ProtocolTypeRouter(
{
# Django's ASGI application to handle traditional HTTP and websocket requests.
"http": URLRouter(http_routes),
"websocket": AuthMiddlewareStack(URLRouter(websocket_routers)),
# ...
}
)
```
Otherwise (if serving under WSGI during development), add the following to the beginning of `urls.py`:
```python
path("", include("django_nextjs.urls"))
```
**Warning:** If you are serving under ASGI, do NOT add this
to your `urls.py`. It may cause deadlocks.
### Setup Next.js URLs (Production Environment)
In production, use a reverse proxy like Nginx or Caddy:
| URL | Action |
| ------------------- | ------------------------------------------ |
| `/_next/static/...` | Serve `NEXTJS_PATH/.next/static` directory |
| `/_next/...` | Proxy to `http://localhost:3000` |
| `/next/...` | Serve `NEXTJS_PATH/public/next` directory |
Pass `x-real-ip` header when proxying `/_next/`. Example config for Nginx:
```conf
location /_next/static/ {
alias NEXTJS_PATH/.next/static/;
expires max;
add_header Cache-Control "public";
}
location /_next/ {
proxy_set_header x-real-ip $remote_addr;
proxy_pass http://127.0.0.1:3000;
}
location /next/ {
alias NEXTJS_PATH/public/next/;
expires max;
add_header Cache-Control "public";
}
```
## Usage
Start Next.js server:
```shell
# Development:
$ npm run dev
# Production:
$ npm run build
$ npm run start
```
Develop your pages in Next.js.
Write a django URL and an async view for each page like this:
```python
from django.http import HttpResponse
from django_nextjs.render import render_nextjs_page
async def jobs(request):
return await render_nextjs_page(request)
```
## Customizing the HTML Response
You can modify the HTML code that Next.js returns in your Django code.
Avoiding duplicate code for the navbar and footer is a common use case
for this if you are using both Next.js and Django templates.
Without it, you would have to write and maintain two separate versions
of your navbar and footer (a Django template version and a Next.js version).
However, you can simply create a Django template for your navbar and insert its code
at the beginning of `<body>` tag returned from Next.js.
To enable this feature, you need to customize the document and root layout
in Next.js and make the following adjustments:
- Add `id="__django_nextjs_body"` as the first attribute of `<body>` element.
- Add `<div id="__django_nextjs_body_begin" />` as the first element inside `<body>`.
- Add `<div id="__django_nextjs_body_end" />` as the last element inside `<body>`.
NOTE: Currently HTML customization is not working with [app router](https://nextjs.org/docs/app) (Next.js 13+).
Read
[this doc](https://nextjs.org/docs/pages/building-your-application/routing/custom-document)
and customize your Next.js document:
```jsx
// pages/_document.jsx (or .tsx)
...
<body id="__django_nextjs_body">
<div id="__django_nextjs_body_begin" />
<Main />
<NextScript />
<div id="__django_nextjs_body_end" />
</body>
...
```
<!-- If you are using Next.js 13+, you also need to
[customize the root layout](https://nextjs.org/docs/app/api-reference/file-conventions/layout)
in `app` directory:
```jsx
// app/layout.jsx (or .tsx)
...
<body id="__django_nextjs_body" className={inter.className}>
<div id="__django_nextjs_body_begin" />
{children}
<div id="__django_nextjs_body_end" />
</body>
...
``` -->
Write a django template that extends `django_nextjs/document_base.html`:
```django
{% extends "django_nextjs/document_base.html" %}
{% block head %}
<!-- ... the content you want to place at the beginning of "head" tag ... -->
{{ block.super }}
<!-- ... the content you want to place at the end of "head" tag ... -->
{% endblock %}
{% block body %}
... the content you want to place at the beginning of "body" tag ...
... e.g. include the navbar template ...
{{ block.super }}
... the content you want to place at the end of "body" tag ...
... e.g. include the footer template ...
{% endblock %}
```
Pass the template name to `render_nextjs_page`:
```python
async def jobs(request):
return await render_nextjs_page(request, "path/to/template.html")
```
## Notes
- If you want to add a file to `public` directory of Next.js,
that file should be in `public/next` subdirectory to work correctly.
- If you're using django channels, make sure all your middlewares are
[async-capable](https://docs.djangoproject.com/en/dev/topics/http/middleware/#asynchronous-support).
- To avoid "Too many redirects" error, you may need to add `APPEND_SLASH = False` in your Django project's `settings.py`. Also, do not add `/` at the end of nextjs paths in `urls.py`.
- This package does not provide a solution for passing data from Django to Next.js. The Django Rest Framework, GraphQL, or similar solutions should still be used.
- The Next.js server will not be run by this package. You will need to run it yourself.
## Settings
Default settings:
```python
NEXTJS_SETTINGS = {
"nextjs_server_url": "http://127.0.0.1:3000",
}
```
### `nextjs_server_url`
The URL of Next.js server (started by `npm run dev` or `npm run start`)
## Development
- Install development dependencies in your virtualenv with `pip install -e '.[dev]'`
- Install pre-commit hooks using `pre-commit install`.
## References
- https://github.com/yourlabs/djnext
- [comment on StackOverflow]
[comment on stackoverflow]: https://stackoverflow.com/questions/54252943/is-there-a-way-to-integrate-django-with-next-js#comment110078700_54252943
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/QueraTeam/django-nextjs",
"name": "django-nextjs",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django,next,nextjs,django-nextjs",
"author": "Mohammad Javad Naderi <mjnaderi@gmail.com>, Danial Keimasi <danialkeimasi@gmail.com>",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/df/3e/451e05284896e40d6e026986f4fd82cc1f186cfeb85a398907d5b7ad3ffc/django-nextjs-2.4.0.tar.gz",
"platform": null,
"description": "# Django Next.js\n\n[](https://pypi.python.org/pypi/django-nextjs/)\n[](https://github.com/QueraTeam/django-nextjs/actions)\n[](https://github.com/QueraTeam/django-nextjs/blob/master/LICENSE)\n[](https://github.com/psf/black)\n\nNext.js integration for Django projects.\n\nSo you want to use both Django and Next.js in your project. There are two scenarios:\n\n1. You are starting a new project and you want to use Django as back-end and Next.js as front-end.\n Django only serves API requests. All front-end code lives in Next.js and you don't write any Django template.\n\n In this scenario you **don't need** this package (although you can use it).\n You simply start both Django and Next.js servers and point your public webserver to Next.js.\n\n2. You need both Django templates and Next.js at the same time and those pages should easily link to each other.\n Maybe you have an existing Django project which has pages rendered by Django template\n and want some new pages in Next.js.\n Or you want to migrate your front-end to Next.js but since the project is large, you need to do it gradually.\n\n In this scenario, **this package is for you!**\n\n## How does it work?\n\nFrom a [comment on StackOverflow]:\n\n> Run 2 ports on the same server. One for django (public facing)\n> and one for Next.js (internal).\n> Let django handle all web requests.\n> For each request, query Next.js from django view to get HTML response.\n> Return that exact HTML response from django view.\n\n## Installation\n\n- Install the latest version from PyPI.\n\n ```shell\n pip install django-nextjs\n ```\n\n- Add `django_nextjs.apps.DjangoNextJSConfig` to `INSTALLED_APPS`.\n\n- Set up Next.js URLs depending on your environment.\n\n### Setup Next.js URLs (Development Environment)\n\nIf you're serving your site under ASGI during development,\nuse [Django Channels](https://channels.readthedocs.io/en/stable/) and\nadd `NextJSProxyHttpConsumer`, `NextJSProxyWebsocketConsumer` to `asgi.py` like the following example.\n\n**Note:** We recommend using ASGI and Django Channels,\nbecause it is required for [fast refresh](https://nextjs.org/docs/architecture/fast-refresh) (hot module replacement) to work properly in Nextjs 12+.\n\n```python\nimport os\n\nfrom django.core.asgi import get_asgi_application\nfrom django.urls import re_path, path\n\nos.environ.setdefault(\"DJANGO_SETTINGS_MODULE\", \"myproject.settings\")\ndjango_asgi_app = get_asgi_application()\n\nfrom channels.auth import AuthMiddlewareStack\nfrom channels.routing import ProtocolTypeRouter, URLRouter\nfrom django_nextjs.proxy import NextJSProxyHttpConsumer, NextJSProxyWebsocketConsumer\n\nfrom django.conf import settings\n\n# put your custom routes here if you need\nhttp_routes = [re_path(r\"\", django_asgi_app)]\nwebsocket_routers = []\n\nif settings.DEBUG:\n http_routes.insert(0, re_path(r\"^(?:_next|__next|next).*\", NextJSProxyHttpConsumer.as_asgi()))\n websocket_routers.insert(0, path(\"_next/webpack-hmr\", NextJSProxyWebsocketConsumer.as_asgi()))\n\n\napplication = ProtocolTypeRouter(\n {\n # Django's ASGI application to handle traditional HTTP and websocket requests.\n \"http\": URLRouter(http_routes),\n \"websocket\": AuthMiddlewareStack(URLRouter(websocket_routers)),\n # ...\n }\n)\n```\n\nOtherwise (if serving under WSGI during development), add the following to the beginning of `urls.py`:\n\n```python\npath(\"\", include(\"django_nextjs.urls\"))\n```\n\n**Warning:** If you are serving under ASGI, do NOT add this\nto your `urls.py`. It may cause deadlocks.\n\n### Setup Next.js URLs (Production Environment)\n\nIn production, use a reverse proxy like Nginx or Caddy:\n\n| URL | Action |\n| ------------------- | ------------------------------------------ |\n| `/_next/static/...` | Serve `NEXTJS_PATH/.next/static` directory |\n| `/_next/...` | Proxy to `http://localhost:3000` |\n| `/next/...` | Serve `NEXTJS_PATH/public/next` directory |\n\nPass `x-real-ip` header when proxying `/_next/`. Example config for Nginx:\n\n```conf\nlocation /_next/static/ {\n alias NEXTJS_PATH/.next/static/;\n expires max;\n add_header Cache-Control \"public\";\n}\nlocation /_next/ {\n proxy_set_header x-real-ip $remote_addr;\n proxy_pass http://127.0.0.1:3000;\n}\nlocation /next/ {\n alias NEXTJS_PATH/public/next/;\n expires max;\n add_header Cache-Control \"public\";\n}\n```\n\n## Usage\n\nStart Next.js server:\n\n```shell\n# Development:\n$ npm run dev\n\n# Production:\n$ npm run build\n$ npm run start\n```\n\nDevelop your pages in Next.js.\nWrite a django URL and an async view for each page like this:\n\n```python\nfrom django.http import HttpResponse\nfrom django_nextjs.render import render_nextjs_page\n\nasync def jobs(request):\n return await render_nextjs_page(request)\n```\n\n## Customizing the HTML Response\n\nYou can modify the HTML code that Next.js returns in your Django code.\n\nAvoiding duplicate code for the navbar and footer is a common use case\nfor this if you are using both Next.js and Django templates.\nWithout it, you would have to write and maintain two separate versions\nof your navbar and footer (a Django template version and a Next.js version).\nHowever, you can simply create a Django template for your navbar and insert its code\nat the beginning of `<body>` tag returned from Next.js.\n\nTo enable this feature, you need to customize the document and root layout\nin Next.js and make the following adjustments:\n\n- Add `id=\"__django_nextjs_body\"` as the first attribute of `<body>` element.\n- Add `<div id=\"__django_nextjs_body_begin\" />` as the first element inside `<body>`.\n- Add `<div id=\"__django_nextjs_body_end\" />` as the last element inside `<body>`.\n\nNOTE: Currently HTML customization is not working with [app router](https://nextjs.org/docs/app) (Next.js 13+).\n\nRead\n[this doc](https://nextjs.org/docs/pages/building-your-application/routing/custom-document)\nand customize your Next.js document:\n\n```jsx\n// pages/_document.jsx (or .tsx)\n...\n<body id=\"__django_nextjs_body\">\n <div id=\"__django_nextjs_body_begin\" />\n <Main />\n <NextScript />\n <div id=\"__django_nextjs_body_end\" />\n</body>\n...\n```\n\n<!-- If you are using Next.js 13+, you also need to\n[customize the root layout](https://nextjs.org/docs/app/api-reference/file-conventions/layout)\nin `app` directory:\n\n```jsx\n// app/layout.jsx (or .tsx)\n...\n<body id=\"__django_nextjs_body\" className={inter.className}>\n <div id=\"__django_nextjs_body_begin\" />\n {children}\n <div id=\"__django_nextjs_body_end\" />\n</body>\n...\n``` -->\n\nWrite a django template that extends `django_nextjs/document_base.html`:\n\n```django\n{% extends \"django_nextjs/document_base.html\" %}\n\n\n{% block head %}\n <!-- ... the content you want to place at the beginning of \"head\" tag ... -->\n {{ block.super }}\n <!-- ... the content you want to place at the end of \"head\" tag ... -->\n{% endblock %}\n\n\n{% block body %}\n ... the content you want to place at the beginning of \"body\" tag ...\n ... e.g. include the navbar template ...\n {{ block.super }}\n ... the content you want to place at the end of \"body\" tag ...\n ... e.g. include the footer template ...\n{% endblock %}\n```\n\nPass the template name to `render_nextjs_page`:\n\n```python\nasync def jobs(request):\n return await render_nextjs_page(request, \"path/to/template.html\")\n```\n\n## Notes\n\n- If you want to add a file to `public` directory of Next.js,\n that file should be in `public/next` subdirectory to work correctly.\n- If you're using django channels, make sure all your middlewares are\n [async-capable](https://docs.djangoproject.com/en/dev/topics/http/middleware/#asynchronous-support).\n- To avoid \"Too many redirects\" error, you may need to add `APPEND_SLASH = False` in your Django project's `settings.py`. Also, do not add `/` at the end of nextjs paths in `urls.py`.\n- This package does not provide a solution for passing data from Django to Next.js. The Django Rest Framework, GraphQL, or similar solutions should still be used.\n- The Next.js server will not be run by this package. You will need to run it yourself.\n\n## Settings\n\nDefault settings:\n\n```python\n NEXTJS_SETTINGS = {\n \"nextjs_server_url\": \"http://127.0.0.1:3000\",\n }\n```\n\n### `nextjs_server_url`\n\nThe URL of Next.js server (started by `npm run dev` or `npm run start`)\n\n## Development\n\n- Install development dependencies in your virtualenv with `pip install -e '.[dev]'`\n- Install pre-commit hooks using `pre-commit install`.\n\n## References\n\n- https://github.com/yourlabs/djnext\n- [comment on StackOverflow]\n\n[comment on stackoverflow]: https://stackoverflow.com/questions/54252943/is-there-a-way-to-integrate-django-with-next-js#comment110078700_54252943\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "",
"summary": "Next.js + Django integration",
"version": "2.4.0",
"project_urls": {
"Download": "https://github.com/QueraTeam/django-nextjs",
"Homepage": "https://github.com/QueraTeam/django-nextjs"
},
"split_keywords": [
"django",
"next",
"nextjs",
"django-nextjs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "381f6dd10a409a60ad1bbe03bad4a87fd4032173e2512a181cf9819fe863e241",
"md5": "153569e0b078e46334e4ab235595efdb",
"sha256": "9ddf7a7a592593d672fa3eca4806c956662569d5cdab04678daf4fab6c0d6383"
},
"downloads": -1,
"filename": "django_nextjs-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "153569e0b078e46334e4ab235595efdb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11214,
"upload_time": "2023-09-02T07:29:29",
"upload_time_iso_8601": "2023-09-02T07:29:29.365379Z",
"url": "https://files.pythonhosted.org/packages/38/1f/6dd10a409a60ad1bbe03bad4a87fd4032173e2512a181cf9819fe863e241/django_nextjs-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "df3e451e05284896e40d6e026986f4fd82cc1f186cfeb85a398907d5b7ad3ffc",
"md5": "ee0897998fdf09f7e288c933a552dd68",
"sha256": "5c81c5a3b47d2c144a9145ee12004f24fbc365c488e8dd8a93c8ec3c12e04a94"
},
"downloads": -1,
"filename": "django-nextjs-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "ee0897998fdf09f7e288c933a552dd68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14325,
"upload_time": "2023-09-02T07:29:31",
"upload_time_iso_8601": "2023-09-02T07:29:31.234531Z",
"url": "https://files.pythonhosted.org/packages/df/3e/451e05284896e40d6e026986f4fd82cc1f186cfeb85a398907d5b7ad3ffc/django-nextjs-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-02 07:29:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "QueraTeam",
"github_project": "django-nextjs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-nextjs"
}
JSON
