Skip to content

Auto PWA (Progressive Web App)

Ushka includes a feature to help you quickly add Progressive Web App capabilities to your front-end. When enabled, Ushka will automatically serve the necessary manifest.webmanifest and a basic sw.js (service worker) file.

This allows your application to be "installable" on users' devices and provides a foundation for offline capabilities.

Enabling "Auto PWA"

The PWA feature is disabled by default. To enable it, you need to add and configure the [pwa] section in your ushka.toml file.

# in ushka.toml

[pwa]
enabled = true
app_name = "My Awesome Ushka App"
short_name = "UshkaApp"
theme_color = "#3367D6"

How It Works

When enabled = true: 1. Ushka registers two routes: * /manifest.webmanifest: This route serves a dynamically generated JSON file based on your ushka.toml configuration. * /sw.js: This route serves a generic, caching-first service worker.

  1. A context processor is added: This processor injects pwa_enabled and pwa_theme_color variables into your Jinja2 templates.

  2. Ushka's default layout template (ushka_layout.html) uses these variables to automatically add the manifest link and theme color meta tag to your HTML's <head> section.

<!-- This is automatically added if you extend the default layout -->
{% if pwa_enabled %}
<meta name="theme-color" content="{{ pwa_theme_color }}">
<link rel="manifest" href="/manifest.webmanifest">
{% endif %}

Configuration

You can customize the web app manifest by setting various properties in the [pwa] section of ushka.toml.

[pwa]
enabled = true
app_name = "My Awesome Ushka App"
short_name = "UshkaApp"
start_url = "/"
display = "standalone" # Can be "standalone", "fullscreen", "minimal-ui", "browser"
background_color = "#FFFFFF"
theme_color = "#3367D6"

Configuring Icons

You can also specify the application icons. The paths should point to icon files in your static directory.

The configuration is done via a list of tables in your ushka.toml:

[pwa]
# ... other settings ...

# Define each icon as a separate table in the list
[[pwa.icons]]
src = "/static/icons/icon-192x192.png"
sizes = "192x192"
type = "image/png"

[[pwa.icons]]
src = "/static/icons/icon-512x512.png"
sizes = "512x512"
type = "image/png"

Customizing the Service Worker

The default service worker (sw.js) is very basic. If you need more advanced offline capabilities, it's recommended to disable the built-in PWA feature (enabled = false) and serve your own custom manifest and service worker files from your static directory.