Changes will sync when you're back online.
```
## Service Worker Configuration
There are two settings surfaces, and which one applies depends on the consumer:
- **`DJUST_CONFIG` flat `PWA_*` keys** (below) are read by `PWAMixin.get_pwa_config()`,
`PWAManifestGenerator` / `manifest_view`, and `ServiceWorkerGenerator` /
`service_worker_view`. The two views only take effect once you route them in
`urls.py`.
- **Plain Django settings `DJUST_PWA_*`** are what the template tags
(`{% djust_pwa_head %}`, `{% djust_pwa_manifest %}`) and `generate_sw` read.
They do **not** read `DJUST_CONFIG`.
There is no `DJUST_PWA` dict setting.
```python
# settings.py
DJUST_CONFIG = {
# Manifest
"PWA_NAME": "My Application",
"PWA_SHORT_NAME": "MyApp",
"PWA_DESCRIPTION": "A djust-powered app",
"PWA_THEME_COLOR": "#007bff",
"PWA_BACKGROUND_COLOR": "#ffffff",
"PWA_DISPLAY": "standalone", # fullscreen | standalone | minimal-ui
"PWA_ICONS": [
{"src": "/static/icons/icon-192.png", "sizes": "192x192", "type": "image/png"},
],
# Service worker
"PWA_CACHE_NAME": "djust-v1",
"PWA_CACHE_STRATEGY": "cache_first", # or "network_first" / "stale_while_revalidate"
"PWA_PRECACHE_URLS": ["/static/css/app.css", "/static/js/app.js"],
"PWA_OFFLINE_PAGE": "/offline/",
"PWA_CACHE_DURATION": 86400,
"PWA_ENABLE_BACKGROUND_SYNC": False,
"PWA_SYNC_ENDPOINT": "/djust/pwa/sync/",
}
```
Unknown `PWA_CACHE_STRATEGY` values silently fall back to `cache_first`.
The template tags take their values from their arguments
(`{% djust_pwa_head name="My App" theme_color="#007bff" %}`) and fall back to
these plain Django settings when an argument is not passed: `DJUST_PWA_NAME`,
`DJUST_PWA_SHORT_NAME`, `DJUST_PWA_DESCRIPTION`, `DJUST_PWA_THEME_COLOR`,
`DJUST_PWA_BACKGROUND_COLOR`.
## Offline Storage
Structured offline data goes through a configurable backend, chosen once for
the project:
```python
DJUST_CONFIG = {
"PWA_OFFLINE_STORAGE": "indexeddb", # or "localstorage"
}
```
`indexeddb` is the default. What a view sets is **not** a backend selector:
```python
class TodoView(OfflineMixin, LiveView):
offline_storage = "todos" # a NAMESPACE, not a backend
```
`offline_storage` is passed through as `storage_name=` — it names the key
space this view persists under, so two views with different values keep
separate data **on the same backend**. To change where data is stored, set
`PWA_OFFLINE_STORAGE`; to change which slice of it a view owns, set
`offline_storage`.
## Example: Offline Todo App
```python
from djust import LiveView
from djust.decorators import event_handler
from djust.pwa.mixins import OfflineMixin
class TodoView(OfflineMixin, LiveView):
template_name = 'todos.html'
def mount(self, request, **kwargs):
self.todos = self.storage.get('todos', [])
@event_handler()
def add_todo(self, text: str = "", **kwargs):
todo = self.create_offline('Todo', {'text': text, 'done': False})
self.todos.append(todo)
self.storage.set('todos', self.todos)
self.sync_when_online()
@event_handler()
def toggle_todo(self, todo_id: str = "", **kwargs):
for todo in self.todos:
if todo['id'] == todo_id:
todo['done'] = not todo['done']
self.update_offline('Todo', todo_id, {'done': todo['done']})
self.storage.set('todos', self.todos)
self.sync_when_online()
```
## Management Commands
```bash
# Basic generation
python manage.py generate_sw
# Custom output path
python manage.py generate_sw --output static/custom-sw.js
# Include static files in the cache
python manage.py generate_sw --cache-static
# Custom cache version (--sw-version: Django reserves --version)
python manage.py generate_sw --sw-version 2.1.0
```
## Adding PWA to an Existing App
1. Add `{% load djust_pwa %}` to your base template
2. Include `{% djust_pwa_head %}` in your ``
3. Mix `PWAMixin` or `OfflineMixin` into your LiveViews
4. Serve the service worker: run `python manage.py generate_sw`, or route `djust.pwa.service_worker_view` at `/sw.js`
5. Deploy with HTTPS (required for service workers in production)
## Browser Support
| Browser | Support |
|---------|---------|
| Chrome / Edge | Full |
| Firefox | Full |
| Safari | Partial (no background sync) |
| Mobile Safari | Full with install prompt |
## Best Practices
- Service workers require HTTPS in production (localhost is exempt for development).
- Use the `network_first` strategy for dynamic content and `cache_first` for static assets.
- Validate data in the sync queue before sending to the server.
- Consider authentication token expiry when designing offline flows.
- Test offline behavior in Chrome DevTools (Application > Service Workers > Offline).