Dynamische ICS-Kalenderfeeds für statische Websites erstellen – so geht’s

Eine Kalenderfunktion in einer statischen Website zu integrieren, erscheint auf den ersten Blick wie eine Aufgabe für einen Backend-Entwickler. Doch was, wenn Ihre gesamte Anwendung nach dem Build-Prozess nur noch aus statischen Dateien besteht? Genau diese Herausforderung stellte sich kürzlich bei Calendana: Ein Feature für abonnierbare Kalenderfeeds musste her – ohne Server, ohne API, allein durch die statische Generierung.

Dabei zeigte sich: Die Lösung lag nicht in komplexen Architekturen, sondern in der cleveren Nutzung der Standards. Mit einem einfachen Post-Build-Skript und präziser Umsetzung der RFC-5545-Vorgaben ließ sich ein voll funktionsfähiges System realisieren. Hier sind die wichtigsten Erkenntnisse und Schritte aus dem Projekt.

Kalenderfeeds als statische Dateien: Ein Paradigmenwechsel

Ein .ics-Feed ist kein Live-API, sondern eine statische Textdatei, die Kalenderanwendungen in regelmäßigen Abständen neu abrufen. Für eine statische Website bedeutet das: Der Feed wird nicht bei jedem Request generiert, sondern einmalig nach dem Build-Prozess erstellt. Der Schlüssel liegt in einem Post-Build-Emitter, der nach dem Kommando next build eine Node.js-Anwendung ausführt und direkt in das Ausgabeverzeichnis out/ schreibt.

# scripts/deploy.sh
npx next build
node scripts/emit-feeds.mjs  # schreibt .ics- und .json-Dateien in out/

Dieser Ansatz bietet mehrere Vorteile:

• Der Feed bleibt immer synchron mit den Daten der Website, da beide aus derselben Quelle gespeist werden.
• Es entstehen keine zusätzlichen Seiten oder Routen – nur reine Dateien.
• Die Implementierung erfordert keine serverseitige Logik.

Der Emitter generiert dabei mehrere Dateitypen:

• Jährliche Feeds (z. B. holidays-de-2026.ics)
• Einzelne Feiertags-Feeds (für direkte Downloads)
• Einen aggregierten Feed für alle Jahre (für Abonnements über webcal://)
• Optional einen JSON-API-Endpunkt unter out/api/

RFC 5545: Die Fallstricke bei All-Day-Events

Die größte Herausforderung lag nicht in der Generierung der Feeds, sondern in der korrekten Umsetzung des RFC-5545-Standards. Besonders tückisch: All-Day-Events. Eine naheliegende Annahme wie DTSTART:20260101 und DTEND:20260101 für einen eintägigen Feiertag führt zu fehlerhaften Darstellungen in einigen Kalenderanwendungen.

Der Grund: DTEND ist ein exklusiver Zeitstempel. Ein All-Day-Event am 1. Januar endet daher erst am 2. Januar um Mitternacht. Die korrekte Darstellung sieht also so aus:

BEGIN:VEVENT
UID:de-2026-neujahr@calendana.com
DTSTAMP:20260614T101500Z
DTSTART;VALUE=DATE:20260101
DTEND;VALUE=DATE:20260102
SUMMARY:Neujahr
TRANSP:TRANSPARENT
CATEGORIES:Holiday
END:VEVENT

Weitere kritische Punkte des Standards, die zu unerwarteten Problemen führen können:

• Zeilenumbrüche: Es müssen CRLF (\r\n) verwendet werden – nicht nur LF (\n).
• Zeilenumbrüche bei langen Texten: Zeilen dürfen maximal 75 Byte lang sein. Bei UTF-8-Zeichen muss darauf geachtet werden, keine mehrbyteigen Codepoints zu trennen.
• Text-Escape-Sequenzen: Zeichen wie Kommas, Semikolons, Backslashes und Zeilenumbrüche in SUMMARY oder DESCRIPTION müssen maskiert werden (\,, \;, \\, \n).
• Stabile UIDs: Jede Änderung der UID zwischen Builds führt dazu, dass Abonnenten bei erneuten Abrufen Duplikate erhalten. Eine deterministische UID wie {locale}-{year}-{key}@domain verhindert dies.

Die Funktion zur korrekten Zeilenumformung ist besonders wichtig, da sie die Byte-gegen-Char-Problematik adressiert:

function foldLine(line) {
  const bytes = new TextEncoder().encode(line);
  if (bytes.length <= 75) return line;

  const dec = new TextDecoder();
  const out = [];
  let start = 0;
  let limit = 75;

  while (start < bytes.length) {
    let end = Math.min(start + limit, bytes.length);
    // Zurücksetzen, falls der Schnitt mitten in einem UTF-8-Codepoint landet
    while (end < bytes.length && (bytes[end] & 0xc0) === 0x80) end--;
    out.push((start === 0 ? "" : " ") + dec.decode(bytes.slice(start, end)));
    start = end;
    limit = 74; // Folgezeilen beginnen mit einem Leerzeichen
  }
  return out.join("\r\n");
}

Deep-Links: Kalenderereignisse ohne .ics-Datei erstellen

Während .ics-Dateien für Downloads und Abonnements ideal sind, fehlt oft die direkte Integration in Kalenderdienste wie Google Calendar oder Outlook. Beide Anbieter bieten jedoch Deep-Link-URLs, die es ermöglichen, Ereignisse ohne vorherige Dateigenerierung direkt im Kalender zu erstellen.

Ein Beispiel für Google Calendar:

function googleHref({ name, date }) {
  const compact = (iso) => iso.replace(/-/g, "");
  const next = nextDay(date); // Ende ist exklusiv
  const p = new URLSearchParams({
    action: "TEMPLATE",
    text: name,
    dates: `${compact(date)}/${compact(next)}`,
  });
  return `
}

Ein einfacher Link ohne JavaScript, der auf einer statischen Seite funktioniert. Für Outlook lautet der entsprechende Deep-Link outlook.live.com/calendar/0/deeplink/compose – ohne den deeplink-Segment wird die Vorbelegung ignoriert.

MIME-Typen und Caching: Die unsichtbaren Stellschrauben

Ein häufiger Fehler bei der Bereitstellung von .ics-Feeds liegt in der falschen Angabe des MIME-Typs. Wird die Datei als text/plain ausgeliefert, verweigern einige Kalenderanwendungen die Verarbeitung. Auf Hosting-Plattformen wie Cloudflare Pages lässt sich dies über eine einfache _headers-Datei im public/-Verzeichnis steuern:

/*.ics
  Content-Type: text/calendar; charset=utf-8
  Cache-Control: public, max-age=86400

/api/*
  Content-Type: application/json; charset=utf-8
  Access-Control-Allow-Origin: *

Diese Konfiguration sorgt dafür, dass:

• Die Feed-Dateien korrekt als Kalenderdaten erkannt werden.
• Die Dateien für einen Tag zwischengespeichert werden, um die Ladezeiten zu optimieren.
• Der JSON-API-Endpunkt für Cross-Origin-Anfragen zugänglich ist.

Die größte Herausforderung: 15 Sprachen, eine konsistente Nutzererfahrung

Ein Kalenderdienst, der in 15 Sprachen angeboten wird, stellt besondere Anforderungen an die Lokalisierung. Die Versuchung ist groß, englische Mikrotexte einfach maschinell zu übersetzen. Doch für eine statische Website mit SEO-Relevanz führt dies schnell zu dünnem, doppelten Content, der von Suchmaschinen abgestraft wird.

Noch kritischer ist die Inkonsistenz bei Kalenderfunktionen: Ein mexikanischer Nutzer erwartet andere Begriffe als ein Spanier oder ein Argentinier – trotz derselben Sprache. Die Lösung lag in einem zentralen Strings-File, das sowohl vom Node.js-Emitter als auch von den React-Komponenten gelesen wird. So bleiben Button-Beschriftungen wie "Agregar a Google Calendar" oder "Añadir" immer synchron mit den Feed-Namen in der Kalenderdatei.

Fazit: Statische Feeds mit maximaler Effizienz

Die Implementierung abonnierbarer Kalenderfeeds für eine statische Website hat gezeigt, dass selbst vermeintlich komplexe Features mit einfachen Mitteln umsetzbar sind. Der Schlüssel lag in der Nutzung vorhandener Standards, der Automatisierung durch Post-Build-Skripte und der strikten Einhaltung von RFC-5545.

Durch die zentrale Datenhaltung und die gemeinsame Nutzung von Strings-Dateien konnte zudem eine Wartungsfreundlichkeit erreicht werden, die auch bei zukünftigen Erweiterungen Bestand hat. Für alle, die ähnliche Projekte planen: Der Aufwand lohnt sich – und der Nutzen für die Besucher ist unmittelbar spürbar.