Skip to content
Marko Schulz 02. February - 00:55 02. February - 01:40

Website als PWA Application einrichten

Um eine Website als Progressive Web App (PWA) bereitzustellen, sodass Nutzer diese wie eine native App auf ihrem Gerät installieren können, musst man einige zentrale Schritte befolgen. PWAs funktionieren sowohl auf Chrome als auch auf anderen modernen Browsern. In diesem Beispiel zeige ich das einrichten eine mkdocs Wikis als PWA.

1. HTTPS aktivieren

PWAs benötigen eine sichere Verbindung (HTTPS), da viele Funktionen (z.B. Service Worker) nur in sicheren Umgebungen erlaubt sind. Daher ist es wichtig, dass die Website unter https:// erreichbar ist.

2. Manifest-Datei (manifest.json) erstellen

Diese Datei beschreibt deine App und sagt dem Browser, wie er sie installieren und anzeigen soll. Sie wird meist im Hauptverzeichnis einer Webseite (z.B. /manifest.json) erstellt. In unserem Fall erstellen wir die Manifest-Datei unter <MCDOCS>/docs/assets/manifest.json.

docs/assets/manifest.json

{
    "name": "IT Knowledge Base",
    "short_name": "IT Wiki",
    "start_url": "/",
    "scope": "/",
    "display": "standalone",
    "orientation": "portrait",
    "background_color": "#ffffff",
    "theme_color": "#4051b5",
    "description": "Gespeichertes Wissen rund um das Thema IT Administration - jederzeit abrufbar.",
    "categories": ["productivity", "education", "utilities"],
    "lang": "de-DE",
    "icons": [
        {
            "src": "/assets/images/icon-192x192.png",
            "sizes": "192x192",
            "type": "image/png",
            "purpose": "any maskable"
        },
        {
            "src": "/assets/images/icon-512x512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ]
}

Wichtige Parameter in der manifest.json

Parameter Beschreibung
name Vollständiger Name der App
short_name Kurzname, der beim Hinzufügen zum Startbildschirm angezeigt wird
description Beschreibung der App
start_url Die URL, die beim Starten der App geöffnet wird
display Steuert das Layout: standalone, fullscreen, minimal-ui, etc.
background_color Hintergrundfarbe des Splash-Screens
theme_color Farbe der Browser-UI beim Starten der App
icons Verschiedene App-Icons in verschiedenen Größen
orientation Bevorzugte Ausrichtung: portrait oder landscape
scope Definiert, welche URLs zur App gehören
lang Sprache der App, z.B. de-DE

3. Manifest in deine HTML einbinden

Füge in den <head>-Bereich deiner HTML-Dateien ein Tag mit der Referenz zur Manifest ein. In unserem Fall definieren wir den Tag in der Datei <MKDOCS>/include/theme/material/overrides/main.html.

<!-- HTML <link/> for the PWA manifest -->
<link rel="manifest" href="/assets/manifest.json">

4. Service Worker einrichten

Der Service Worker ist ein Skript, das im Hintergrund läuft und Funktionen wie Offline-Unterstützung ermöglicht.

Service Worker registrieren

Wir fügen folgenden Code in unsere <MKDOCS>/docs/assets/javascript/custom.js hinzu.

if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/assets/javascript/service-worker.js')
        .then((registration) => {
            console.log('Service Worker registriert:', registration.scope);
        })
        .catch((error) => {
            console.error('Service Worker Registrierung fehlgeschlagen:', error);
        });
}

Service Worker-Skript

Wir erstellen den folgenden Service Worker in <MKDOCS>/docs/assets/javascript/service-worker.js.

const CACHE_NAME = 'it-wiki-cache-v1';
const urlsToCache = [
  '/',
  '/index.html',
  '/offline.html', // Optional, falls du eine Offline-Seite anzeigen willst

  // Stylesheets
  '/assets/stylesheets/main.6f8fc17f.min.css',
  '/assets/stylesheets/palette.06af60db.min.css',
  '/assets/stylesheets/Font-awesome.min.css',
  '/assets/stylesheets/Fonts-Roboto.css',
  '/assets/stylesheets/custom.css',
  '/assets/stylesheets/custom.f7ec4df2.min.css',
  '/assets/_mkdocstrings.css',

  // JavaScripts
  '/assets/javascripts/bundle.88dd0f4e.min.js',
  '/assets/javascript/jquery.min.js',
  '/assets/javascript/custom.js',
  '/assets/javascripts/custom.149a65e0.min.js',
  '/assets/javascripts/workers/search.6ce7567c.min.js',

  // Fonts
  '/assets/fonts/Roboto-Regular.woff2',
  '/assets/fonts/Roboto-Bold.woff2',

  // Bilder und Icons (falls vorhanden)
  '/assets/images/icon-192x192.png',
  '/assets/images/icon-512x512.png'
];

// Installations-Event: Ressourcen cachen
self.addEventListener('install', event => {
  console.log('Service Worker installiert.');
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => {
        console.log('Dateien werden in den Cache geladen.');
        return cache.addAll(urlsToCache);
      })
  );
});

// Fetch-Event: Aus Cache laden oder aus dem Netz, falls nicht verfügbar
self.addEventListener('fetch', event => {
  console.log('Fetch-Anfrage für:', event.request.url);
  event.respondWith(
    caches.match(event.request)
      .then(response => {
        // Rückgabe der gecachten Datei, falls gefunden
        if (response) {
          console.log('Aus Cache geladen:', event.request.url);
          return response;
        }
        // Wenn nicht im Cache, aus dem Netz laden
        console.log('Aus dem Netz geladen:', event.request.url);
        return fetch(event.request);
      })
      .catch(() => {
        // Fallback, wenn weder Cache noch Netz verfügbar sind
        return caches.match('/offline.html'); 
      })
  );
});

// Optional: Alter Cache bei neuer Version löschen
self.addEventListener('activate', event => {
  const cacheWhitelist = [CACHE_NAME];
  event.waitUntil(
    caches.keys().then(cacheNames => {
      return Promise.all(
        cacheNames.map(cacheName => {
          if (!cacheWhitelist.includes(cacheName)) {
            console.log('Alter Cache gelöscht:', cacheName);
            return caches.delete(cacheName);
          }
        })
      );
    })
  );
});

Erklärung der Erweiterungen

Caching bei der Installation - Im install-Event wird urlsToCache geöffnet und alle Ressourcen werden in den Cache geladen. Damit kann deine PWA offline auf diese Dateien zugreifen.

Fetch mit Cache-Fallback - Bei jeder Anforderung (fetch) wird zuerst geprüft, ob die Datei im Cache liegt. Wenn ja, wird die gecachte Version verwendet, andernfalls wird die Datei aus dem Netzwerk geladen.

Cache Bereinigung bei Aktivierung - Beim activate-Event werden alte Caches gelöscht, damit du keine veralteten Daten behältst, wenn du z.B. die Cache-Version änderst.

5. Testen & Debugging

Chrome DevTools öffnen (F12) → Tab Application → Prüfen:

  • Unter Manifest wird deine `manifest.json`` angezeigt.
  • Unter Service Workers kannst du sehen, ob der Service Worker aktiv ist.

Wenn alles korrekt eingerichtet ist, zeigt der Browser ein Installieren-Symbol in der Adressleiste oder in den Browser-Optionen an.

6. Optional: iOS-Unterstützung

iOS unterstützt PWAs nicht vollständig wie Android, aber du kannst die Installation erleichtern

Meta-Tags für iOS hinzufügen

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<link rel="apple-touch-icon" href="/icons/icon-192x192.png">

7. Offizielle Dokumentationen zu PWAs