django-browser-reload
Automatically reload your browser in development.
Requirements
Python 3.6 to 3.10 supported.
Django 2.2 to 4.0 supported.
Are your tests slow? Check out my book Speed Up Your Django Tests which covers loads of best practices so you can write faster, more accurate tests.
Installation
Install with pip:
python -m pip install django-browser-reload
Ensure you have
"django.contrib.staticfiles"in yourINSTALLED_APPS.Add django-browser-reload to your
INSTALLED_APPS:INSTALLED_APPS = [ ..., "django_browser_reload", ..., ]
Include the app URL’s in your root URLconf(s):
from django.urls import include, path urlpatterns = [ ..., path("__reload__/", include("django_browser_reload.urls")), ]
You can use another prefix if required.
Add the template tag to your base template. This can go anywhere, but it’s best just before
</body>:{% load django_browser_reload %} ... {% django_browser_reload_script %} </body> </html>To add django-browser-reload to Django’s admin, do so in a template called
admin/base_site.html:{% extends "admin/base_site.html" %} {% load django_browser_reload %} {% block extrahead %} {{ block.super }} {% django_browser_reload_script %} {% endblock %}This follows Django’s documentation on extending an overriden template.
All done!
For faster and more efficient reloading, also set up Django’s built-in Watchman support.
What It Does
When DEBUG is True, the template tag includes a small script. This script connects back to the development server and will automatically reload when runserver restarts, or a template is modified. (Template modification detection requires Django 3.2+.) The reload only happens in the most recently opened tab.
Example App
See the example app in the example/ directory of the GitHub repository. Start it up, and try modifying example/core/views.py or templates/index.html to see the reloading in action.
How It Works
Here’s a diagram:
Browser
Tab 1 Tab 2 Tab N
listener listener listener
\ | /
Django \ | /
\ | /
Events View --------------------> Shared worker
The template tag includes a listener script on each page. This listener script starts or connects to a SharedWorker, running a worker script. The worker script then connects to the events view in Django, using an EventSource to receive server-sent events.
This event source uses StreamingHttpResponse to send events to the worker. The view continues streaming events indefinitely, until disconnected. (This requires a thread and will not work if you use runserver’s --nothreading option.)
On a relevant event, the worker will reload the most recently connected tab. (It avoids reloading all tabs since that could be expensive.)
To reload when a template changes, django-browser-reload piggybacks on Django’s autoreloading infrastructure. An internal Django signal indicates when a template file has changed. The events view receives this signal and sends an event to the worker, which triggers a reload. There is no smart filtering - if any template file changes, the view is reloaded.
To reload when the server restarts, django-browser-reload uses a version ID. This ID is randomly generated when the view module is imported, so it will be different every time the server starts. When the server restarts, the worker’s EventSource reconnects with minimal delay. On connection, the events view sends the version ID, which the worker sees as different, so it triggers a reload.
The events view also sends the version ID every second to keep the connection alive.
Compatibility
EventSource is highly compatible. SharedWorker is a bit less so, but should work with Chrome, Edge, Firefox, and Opera.
23 Sep 16, 2021
814 Dec 26, 2022
19 Oct 22, 2022
1 Nov 27, 2021
838 Dec 30, 2022
155 Dec 14, 2022
384 Nov 23, 2022
59 Dec 21, 2022
33 Dec 22, 2022
1.7k Jan 1, 2023
2.7k Jan 7, 2023
2.1k Dec 29, 2022
2.1k Dec 30, 2022
909 Dec 26, 2022
2.1k Dec 24, 2022
687 Jan 4, 2023
1.3k Dec 30, 2022
22 Nov 22, 2022