Automatically reload your browser in development.
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/django-browser-reload/main.yml?branch=main&style=for-the-badge :target: https://github.com/adamchainz/django-browser-reload/actions?workflow=CI
.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge :target: https://github.com/adamchainz/django-browser-reload/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/django-browser-reload.svg?style=for-the-badge :target: https://pypi.org/project/django-browser-reload/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge :target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge :target: https://github.com/pre-commit/pre-commit :alt: pre-commit
Automatically reload your browser in development.
Work smarter and faster with my book Boost Your Django DX <https://adamchainz.gumroad.com/l/byddx>
__ which covers django-browser-reload and many other tools.
I wrote django-browser-reload whilst working on the book!
Python 3.8 to 3.12 supported.
Django 3.2 to 5.0 supported.
WSGI supported on all Django versions. ASGI supported on Django 4.2+.
Your browser needs to support:
|EventSource|__ - universally available.
.. |EventSource| replace:: EventSource
__ https://developer.mozilla.org/en-US/docs/Web/API/EventSource#browser_compatibility
|SharedWorker|__ - available on Chrome, Edge, Firefox, and Opera for a long time. Available on Safari since version 16 (2022-09-12).
.. |SharedWorker| replace:: SharedWorker
__ https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker#browser_compatibility
Install with pip:
.. code-block:: sh
python -m pip install django-browser-reload
Ensure you have "django.contrib.staticfiles"
in your INSTALLED_APPS
.
Add django-browser-reload to your INSTALLED_APPS
:
.. code-block:: python
INSTALLED_APPS = [
...,
"django_browser_reload",
...,
]
Include the app URLs in your root URLconf:
.. code-block:: python
from django.urls import include, path
urlpatterns = [
...,
path("__reload__/", include("django_browser_reload.urls")),
]
You can use another prefix if required.
Add the middleware:
.. code-block:: python
MIDDLEWARE = [ # ... "django_browser_reload.middleware.BrowserReloadMiddleware", # ... ]
The middleware should be listed after any others that encode the response, such as Django’s GZipMiddleware
.
The middleware automatically inserts the required script tag on HTML responses before </body>
when DEBUG
is True
.
It does so to every HTML response, meaning it will be included on Django’s debug pages, admin pages, etc.
If you want more control, you can instead insert the script tag in your templates—see below.
All done! 📯
For faster and more efficient reloading, also set up Django’s built-in Watchman support <https://adamj.eu/tech/2021/01/20/efficient-reloading-in-djangos-runserver-with-watchman/>
__.
When DEBUG
is True
, the template tag includes a small script.
This script connects back to the development server and will automatically reload when static assets or templates are modified, or after runserver
restarts.
The reload only happens in the most recently opened tab.
See the example project <https://github.com/adamchainz/django-browser-reload/tree/main/example>
__ in the example/
directory of the GitHub repository.
Start it up and modify its files to see the reloading in action.
If the middleware doesn’t work for you, you can also use a template tag to insert the script on relevant pages.
The template tag has both Django templates and Jinja versions, and only outputs the script tag when DEBUG
is True
.
For Django Templates, load the tag and use it in your base template.
The tag can go anywhere, but it’s best just before </body>
:
.. code-block:: html
{% load django_browser_reload %}
...
{% django_browser_reload_script %}
</body>