Wie man eine Kalender-App erstellt – Ein umfassender Leitfaden

Wenn Sie als Entwickler damit beauftragt sind, einen Kalender in Ihre Anwendung zu integrieren, oder als Unternehmer darüber nachdenken, eine Kalender-App (oder eine App mit Kalender-Integrationen) zu bauen, ist dieser Artikel für Sie.

Lernen wir gemeinsam, wie man eine Kalender-App entwickelt: Schritt für Schritt Entscheidungen treffen, die besten Technologien auswählen sowie Herausforderungen und Best Practices verstehen.

Was ist der Umfang dieses Artikels?

Wie in der Einleitung erwähnt, ist das Ziel dieses Artikels, Ihnen zu helfen, entweder eine vollwertige Kalender-App zu entwickeln oder Kalenderanbieter in Ihre bestehende Anwendung zu integrieren, sodass Nutzer ihre Kalender verbinden und über Ihre App verwalten können.

Dieser Artikel ist auch dann hilfreich, wenn Sie Kalenderanbieter integrieren möchten, ohne eine eigene Kalenderoberfläche bereitzustellen. Beispiele wären eine Aufgaben-App, eine Dating-App oder sogar ein Feature, das Ereignisse in die Kalender eines Nutzers einträgt.

Sie können gerne Teile des Artikels in Ihrem Code verwenden – inklusive Technologieentscheidungen, Unified APIs oder Code-Ausschnitten.

Überblick über Architektur & Tech-Stack

Als Plattform wählen wir das Web, da es einfacher in Betrieb zu nehmen ist und es viel Community-Support für Kalender-Bibliotheken gibt.

Die Programmiersprache ist TypeScript, das Web-Framework ist Next.js.

Hier ist ein Überblick über den Tech-Stack, den wir verwenden:

• Frontend: Next.js (App Router, TypeScript)
• Backend: Next.js API Routes + tRPC
• Datenbank: PostgreSQL (mit Prisma als ORM)
• Calendar APIs: OneCal Unified Calendar API
• Hosting: Anbieterunabhängig, z. B. Vercel oder wo auch immer Sie sich wohlfühlen
• Authentifizierung: OAuth2 (Google, Microsoft) über better-auth

Unten sehen Sie das Architekturdiagramm und wie der Tech-Stack zusammenspielt:

Definitionen:

• Client (1): Das Endgerät des Nutzers. In der Illustration wird ein Mobilgerät gezeigt, aber es kann auch ein Desktop, Laptop usw. sein (ein Gerät mit Webbrowser wie Google Chrome). Der Client rendert das Next.js-Frontend, verarbeitet Nutzerinteraktionen und kommuniziert per HTTPS sicher mit dem Backend.

• Webserver (2): Der Webserver hostet und liefert die Benutzeroberfläche, eine Next.js-(App Router)-Webanwendung. Er stellt optimiertes HTML, CSS und JavaScript bereit und ermöglicht Server-Side Rendering (SSR) sowie Incremental Static Regeneration (ISR) für schnelle Performance und SEO-Vorteile.

• Next.js API (3): Die Next.js API dient als Backend-Schicht, implementiert mit API Routes und tRPC in derselben Next.js-Anwendung. Sie ist der zentrale Knoten, der Frontend, Datenbank und externe Integrationen wie die OneCal Unified Calendar API verbindet. Anders als klassische REST-Endpoints ermöglicht tRPC typsichere, Ende-zu-Ende-Kommunikation zwischen Frontend und Backend, ohne ein separates API-Schema definieren zu müssen. Der Client kann Backend-Prozeduren direkt aufrufen – mit vollständiger TypeScript-Typinferenz. Das beschleunigt die Entwicklung und reduziert Laufzeitfehler.

• PostgreSQL (4): Die PostgreSQL-Datenbank speichert alle persistenten Anwendungsdaten, darunter Nutzer, Sessions, verbundene Kalenderkonten usw. Sie ist das System of Record für alle nutzerbezogenen Daten und Synchronisationszustände. Mit Prisma als ORM-Schicht wird das Schema sauber auf die Datenbank abgebildet, was Migrationen und Abfragen vereinfacht.

• OneCal Unified Calendar API (5): Die OneCal Unified Calendar API ist die API, die wir nutzen, um alle Kalenderanbieter über eine standardisierte API anzubinden. OneCal Unified macht es leicht, alle Anbieter zu integrieren, ohne für jeden eine eigene Implementierung zu schreiben, unterschiedliche Datenstrukturen zu behandeln, mehrere Integrationen zu pflegen oder auf API-Änderungen reagieren zu müssen. Unsere API kommuniziert mit der OneCal Unified Calendar API, indem sie den API-Schlüssel und die Kalender angibt, auf denen wir Operationen ausführen wollen (CRUD von Events, Kalendern u. m.) – unabhängig vom Anbieter. Im Gegenzug kommuniziert OneCal mit den Anbietern und liefert die Antwort in einem standardisierten Format für alle Kalenderanbieter.

Beachten Sie, dass der Webserver (2) und die Next.js API (3) auf demselben Server gehostet werden können (z. B. via Vercel, Docker etc.). Im Diagramm sind sie nur getrennt dargestellt, um visuell zu verdeutlichen, dass es eine UI- und eine API-Schicht gibt, auch wenn beide im selben Next.js-Codebestand leben und in der Regel zusammen gehostet werden.

Das Datenmodell entwerfen

Nach der Architektur und dem Tech-Stack definieren wir das Datenmodell. Als ORM verwenden wir Prisma.

Dieses Prisma-Schema definiert die Datenstruktur für eine grundlegende Kalender-Anwendung, die Nutzer-Authentifizierung, verbundene Kalenderkonten (Google, Microsoft) und Ereignis-Synchronisation über eine Unified API unterstützt.

Die wichtigsten Modelle sind:

1. User

Repräsentiert einen Endnutzer der App. Jeder Nutzer kann mehrere Sessions, verbundene Konten (OAuth) und Kalenderkonten haben. Felder wie email, name und onboardingCompletedAt helfen, Profil- und Onboarding-Status nachzuverfolgen.

2. CalendarAccount

Repräsentiert ein verknüpftes externes Kalenderkonto (z. B. ein Google- oder Microsoft-Konto). Es speichert provider, email und status (aktiv oder abgelaufen). Jedes CalendarAccount gehört zu genau einem User und kann mehrere Calendar-Einträge enthalten.

3. Calendar

Repräsentiert einen einzelnen Kalender (z. B. „Arbeit“, „Privat“ oder „Familie“) innerhalb eines verknüpften Kontos. Enthält Anzeige-Felder wie name, color, timezone sowie Flags wie isPrimary oder isReadOnly. Jeder Kalender ist sowohl einem User als auch dem zugehörigen CalendarAccount zugeordnet.

4. Account

Verwaltet Daten zu OAuth-Anbietern (Google oder Microsoft). Speichert Access- und Refresh-Tokens, Ablaufzeiten und Scope-Informationen für Authentifizierung und Kalendersynchronisation.

5. Session

Verfolgt aktive Login-Sitzungen der Nutzer. Enthält Felder wie token, expiresAt, ipAddress und userAgent, um aktive Sitzungen zu verwalten und abzusichern.

6. Verification

Wird für einmalige Verifizierungen genutzt, z. B. E-Mail-Login per Magic Link oder Codes für passwortlose Anmeldung. Speichert temporäre Kennungen und Ablaufzeiten.

7. Enums

• CalendarAccountProvider: Unterstützte Anbieter (GOOGLE, MICROSOFT)
• CalendarAccountStatus: Verfolgt, ob ein verbundenes Konto ACTIVE oder EXPIRED ist

Das ER-Diagramm der Datenbank:

Öffnen Sie bitte die schema.prisma-Datei in unserem GitHub-Repository, um das vollständige Datenbankschema einschließlich Typen und Beziehungen zu sehen.

Das Backend bauen

Wie erwähnt, verwenden wir Next.js API Routes für die API, da es praktisch ist, UI und API im selben Codebestand zu haben und auf demselben Server zu hosten. Das bedeutet, dass Sie UI und API gleichzeitig ausführen können.

Die Authentifizierung aufbauen

Wir verwenden better-auth als Authentifizierungs-Framework. Better Auth macht Authentifizierung sehr einfach und unkompliziert. Bitte folgen Sie der Better-Auth-Anleitung zur Integration von Better Auth mit Next.js; die Schritte sind nahezu identisch. Sie können auch die Auth-Datei in unserem Repository ansehen.

Die OneCal Unified Calendar API einrichten, um mit allen Kalenderanbietern zu kommunizieren

Der größte Schmerzpunkt beim Bau einer Kalender-App oder bei der Integration von Kalendern in ein bestehendes Produkt ist der Umgang mit anbieter-spezifischen APIs. Das kostet Zeit, da man jede API separat erlernen, unterschiedliche Datenstrukturen, Requests und Responses handhaben und für jeden Anbieter eine eigene Integration bauen und danach pflegen muss.

Eine hervorragende Lösung ist eine Unified-Calendar API, die uns hilft, alle Kalenderanbieter über eine standardisierte API anzubinden. In diesem Beispiel verwenden wir die OneCal Unified Calendar API.

So starten Sie mit OneCal Unified:

1. Schritt eins: Bei OneCal Unified registrieren und ein kostenloses Konto anlegen.

   

2. Nach der Registrierung aktivieren Sie die Kalenderanbieter, die Sie integrieren möchten. Wir empfehlen Google Calendar und Outlook zu aktivieren, um die Vorteile eines Unified-Kalender-Produkts zu verstehen. Beachten Sie, dass Sie keinen eigenen Google- oder Microsoft-Client anlegen müssen: Für Sandbox und Entwicklung können Sie den OneCal Unified Google Client verwenden, um Outlook- oder Google-Konten mit Ihrer Anwendung zu verbinden.

   

3. Erstellen Sie einen API-Schlüssel und speichern Sie ihn in der Umgebungsvariable ONECAL_UNIFIED_API_KEY.

   

Den OneCal Unified API-Client bauen

Nachdem die OneCal Unified Calendar API eingerichtet und der API-Schlüssel abgerufen wurde, bauen wir den API-Client, der mit der OneCal Unified Calendar API interagiert:

import { env } from "@/env";
import type {
  EndUserAccount,
  PaginatedResponse,
  UnifiedCalendar,
  UnifiedEvent as UniversalEvent,
} from "@/server/lib/onecal-unified/types";
import ky from "ky";

export const onecalUnifiedApi = ky.create({
  prefixUrl: env.NEXT_PUBLIC_ONECAL_UNIFIED_URL,
  headers: {
    "x-api-key": env.ONECAL_UNIFIED_API_KEY,
  },
});

export async function getEndUserAccountById(id: string) {
  const response = await onecalUnifiedApi.get<EndUserAccount>(
    `endUserAccounts/${id}`,
  );
  return response.json();
}

export async function getCalendarsForEndUserAccount(endUserAccountId: string) {
  const response = await onecalUnifiedApi.get<
    PaginatedResponse<UnifiedCalendar>
  >(`calendars/${endUserAccountId}`);
  return response.json();
}

interface GetCalendarEventsParams {
  pageToken?: string;
  pageSize?: number;
  syncToken?: string;
  startDateTime?: string;
  endDateTime?: string;
  timeZone?: string;
  expandRecurrences?: boolean;
}

export async function getCalendarEvents(
  endUserAccountId: string,
  calendarId: string,
  params: GetCalendarEventsParams = {},
) {
  const queryParams = new URLSearchParams(params as Record<string, string>);

  const response = await onecalUnifiedApi.get<
    PaginatedResponse<UniversalEvent>
  >(`events/${endUserAccountId}/${calendarId}?${queryParams}`);
  return response.json();
}

export async function getCalendarEvent(
  endUserAccountId: string,
  calendarId: string,
  eventId: string,
) {
  const response = await onecalUnifiedApi.get<UniversalEvent>(
    `events/${endUserAccountId}/${calendarId}/${eventId}`,
  );
  return response.json();
}

export async function createCalendarEvent(
  endUserAccountId: string,
  calendarId: string,
  event: Partial<UniversalEvent>,
) {
  const response = await onecalUnifiedApi.post<UniversalEvent>(
    `events/${endUserAccountId}/${calendarId}`,
    {json: event},
  );
  return response.json();
}

export async function editCalendarEvent(
  endUserAccountId: string,
  calendarId: string,
  eventId: string,
  event: Partial<UniversalEvent>,
) {
  const response = await onecalUnifiedApi.put<UniversalEvent>(
    `events/${endUserAccountId}/${calendarId}/${eventId}`,
    {json: event},
  );
  return response.json();
}

export async function deleteCalendarEvent(
  endUserAccountId: string,
  calendarId: string,
  eventId: string,
) {
  await onecalUnifiedApi.delete(
    `events/${endUserAccountId}/${calendarId}/${eventId}`,
  );
}

Die Client-Typen und weitere relevante Klassen finden Sie an diesem GitHub-Ort.

Das Sequenzdiagramm erklärt, wie die Beispiel-Kalender-App mit der OneCal Unified Calendar API interagiert, um eine nahtlose Integration mit allen Kalenderanbietern bereitzustellen.

Die API-Routes erstellen

Nachdem der OneCal Unified-Client eingerichtet ist, können wir die API-Routes zum Verwalten von Kalenderkonten und Kalenderereignissen erstellen. Eigene Session-APIs müssen wir nicht definieren, da wir hierfür BetterAuth nutzen.

Die API enthält Routen-Definitionen für:

• Kalenderkonten: HTTP-Methoden zum Auflisten aller Kalenderkonten und zum Löschen eines Kontos per ID.
• Kalenderereignisse: HTTP-Methoden für CRUD-Operationen auf Ereignissen.
• Kalender: HTTP-Methoden zum Aktualisieren von Kalendern.

Eine Routen-Definition mit tRPC sieht z. B. so aus: ⁠

export const calendarEventsRouter = createTRPCRouter({
  getCalendarEvent: publicProcedure
    .input(
      z.object({
        endUserAccountId: z.string(),
        calendarId: z.string(),
        eventId: z.string(),
      }),
    )
    .query(async ({ ctx, input }) => {
      return await getCalendarEvent(
        input.endUserAccountId,
        input.calendarId,
        input.eventId,
      );
    }),
});

Die Methode getCalendarEvent stammt aus dem oben gebauten OneCal Unified-Client.

Öffnen Sie bitte den API-Routes-Pfad in unserem GitHub-Repository, um die Inhalte jeder API-Route zu sehen – ein Einfügen hier wäre sehr repetitiv.

Das Frontend bauen

Das Frontend wird mit Next.js + TypeScript gebaut. Beim Erstellen einer Kalender-App ist die wichtigste Komponente … genau: der Kalender.

Aus unserer Erfahrung sind die besten Kalender-UI-Bibliotheken in Next.js und React:

• react-big-calendar
• @fullcalendar/react

Für dieses Beispiel haben wir react-big-calendar gewählt, da es sich leicht mit Next.js nutzen lässt. Für Produktions-Apps würden wir jedoch fullcalendar empfehlen, weil es anpassbarer ist und eine größere Community hat.

Außerdem ist fullcalendar auch für andere Bibliotheken verfügbar, etwa Svelte, Vue.js usw.

react-big-calendar – Verwendung:

     <Calendar
        culture="en-US"
        localizer={localizer}
        events={events}
        defaultView="week"
        eventPropGetter={eventPropGetter}
        components={components}
        onSelectSlot={(slotInfo) => {
          setCreateEventStart(slotInfo.start);
          setCreateEventEnd(slotInfo.end);
          setCreateEventOpen(true);
        }}
        onSelectEvent={(event) => {
          setSelectedEvent(event);
        }}
        selectable
        onRangeChange={(range) => {
          // Week view: range is array of dates
          if (Array.isArray(range) && range.length >= 2) {
            setDateRange([range[0]!, range[range.length - 1]!]);
            return;
          }
          // Month view: range is object with start/end
          if (
            range &&
            typeof range === "object" &&
            "start" in range &&
            "end" in range
          ) {
            setDateRange([range.start, range.end]);
            return;
          }
          // Day view: range is a single Date
          if (range instanceof Date) {
            setDateRange([range, range]);
            return;
          }
        }}
      />

Die vollständige Implementierung finden Sie im Pfad src/app/(protected)/(calendar) im GitHub-Repo. Die Hauptkomponente ist die Seite events-calendar.tsx. Dort gibt es auch Komponenten zum Bearbeiten (inkl. Serientermine), Löschen und Erstellen von Ereignissen.

So sieht der Kalender aus:

Der Nutzer kann in eine Zelle klicken und ein Ereignis erstellen:

Klickt der Nutzer auf ein bestehendes Ereignis, kann er es löschen oder bearbeiten.

Bei Serienterminen kann der Nutzer entscheiden, ob nur die ausgewählte Instanz oder die gesamte Serie bearbeitet werden soll.

So sieht die Bearbeiten-Ansicht aus:

Die UI braucht noch Feinschliff, aber unser Ziel war es nicht, eine perfekte Kalender-App zu bauen. Es geht darum, eine funktionale Kalender-App und Integration zu erstellen – die Gestaltung können Sie an Ihre Marke anpassen.

Häufige Herausforderungen und Best Practices

Eine Kalender-App zu bauen oder Kalender-Funktionen hinzuzufügen, ist nicht immer einfach. Selbst wenn die Hauptfunktionalität simpel wirkt, gibt es viele Details, die später Probleme verursachen können. Im Folgenden finden Sie typische Herausforderungen und Best Practices.

1. Zeitzonen

Herausforderung:

Ereignisse können zur falschen Zeit erscheinen, wenn Nutzer in unterschiedlichen Zeitzonen sind.

Best Practice:

• Zeiten in der Datenbank immer in UTC speichern. (Ausnahme: Kalenderereignisse – wir empfehlen nicht, diese in Ihrer Datenbank zu speichern. Beim Abrufen über die API des Kalenderanbieters erhalten Sie auch die Ereignis-Zeitzone.)
• Für die Anzeige im Frontend in die lokale Zeit des Nutzers umrechnen.
• Eine Bibliothek wie date-fns-tz oder luxon für Konvertierungen nutzen. In diesem Beispiel verwenden wir date-fns und date-fns-tz.

2. Serientermine

Herausforderung:

Wiederholende Ereignisse (täglich, wöchentlich, monatlich) sind komplex – besonders wenn Nutzer eine einzelne Instanz bearbeiten oder löschen möchten.

Best Practice:

• Den Nutzer wählen lassen, ob nur dieses Ereignis oder die gesamte Serie aktualisiert werden soll. So handhaben es Google Calendar, Outlook und viele andere Clients – und auch unsere Beispiel-App.

3. OAuth-Token-Ablauf

Herausforderung:

Wenn Tokens ablaufen oder widerrufen werden, verlieren Nutzer die Verbindung zu ihren Kalendern.

Best Practice:

• Refresh-Tokens sicher speichern, um automatisch neue Access-Tokens zu erhalten.
• Token-Fehler robust behandeln und Nutzer bei Bedarf freundlich auffordern, ihr Konto neu zu verbinden.

4. Daten synchron halten

Herausforderung:

Kalenderdaten veralten, wenn sie nur einmal abgerufen werden.

Best Practice:

• Webhooks der OneCal Unified Calendar API verwenden, um bei Änderungen informiert zu bleiben.
• Ereignisse beim Nutzer-Kontext abrufen (z. B. wenn der Nutzer den Kalender benutzt). Bitte speichern Sie Ereignisse nicht in Ihrer Datenbank – die Synchronisation mit allen Anbietern ist schwierig. Zudem ist der Mehrwert gering, da Sie Ereignisse über die OneCal Unified Calendar API jederzeit abrufen können.

5. API-Fehler handhaben

Herausforderung:

Externe APIs (Google, Outlook, iCloud) können Fehler, Rate Limits oder temporäre Ausfälle liefern.

Best Practice:

• Retry-Logik für temporäre Fehler einbauen (Timeouts sind eine Option).
• Rate Limits respektieren und Backoff einsetzen. Beachten Sie, dass sowohl die OneCal Unified Calendar API als auch die Anbieter (Google Calendar / Outlook Calendar) Limits setzen.
• Fehlgeschlagene Requests protokollieren, um Debugging zu erleichtern.

6. Große Kalender

Herausforderung:

Manche Nutzer haben Hunderte oder Tausende Ereignisse – das kann die App verlangsamen.

Best Practice:

• Ereignisse seitenweise laden (Pagination). Alle großen Anbieter unterstützen Pagination. Die OneCal Unified Calendar API paginiert Ergebnisse standardmäßig.
• Nur Ereignisse im sichtbaren Zeitraum abrufen (z. B. Woche oder Monat). Grundsätzlich gilt: nur so viele Daten laden, wie benötigt werden (Tag-, Wochen-, Monats-, Jahresansicht → jeweils passende Zeitspanne abrufen).

7. Privatsphäre und Sicherheit

Herausforderung:

Kalenderdaten enthalten oft private Informationen.

Best Practice:

• Kalenderereignisse nicht in Ihrer Datenbank speichern. Das Speichern von Access- und Refresh-Tokens genügt.
• Tokens und sensible Felder in der Datenbank verschlüsseln. Wir empfehlen Verschlüsselung „at rest“; Dienste wie AWS RDS bieten dies out-of-the-box.
• Nutzern jederzeit ermöglichen, ihre Kalenderkonten zu trennen. Andernfalls widerrufen sie den Zugriff direkt in ihrem Google-Konto – ohne sauberen Zustand in Ihrer Anwendung.

FAQ

1. Kann ich anstelle von Next.js API Routes ein anderes Backend verwenden?

Ja. Obwohl dieses Beispiel Next.js API Routes mit tRPC nutzt, können Sie jedes Backend-Framework einsetzen, z. B. Nest.js, Express oder Django. Entscheidend ist, dass Ihr Backend per HTTPS mit der OneCal Unified Calendar API kommuniziert. Datenbankstruktur und API-Logik bleiben weitgehend gleich.

2. Muss ich eigene Google- oder Microsoft-Entwickler-Apps erstellen?

Nein, während der Entwicklung können Sie die OneCal Unified Google- und Microsoft-Clients verwenden. Für den Live-Betrieb können Sie eigene OAuth2-Credentials erstellen, wenn Sie volle Kontrolle und Ihr eigenes Branding wünschen.

3. Kann ich eine andere Datenbank als PostgreSQL nutzen?

Ja. Prisma unterstützt u. a. MySQL, SQLite und MongoDB. Wir haben PostgreSQL gewählt, weil es zuverlässig, skalierbar und für Produktion leicht einzurichten ist. Sie können je nach Tech-Stack auch andere Datenbanken und ORMs nutzen.

4. Ist die OneCal Unified Calendar API kostenlos?

Sie können mit einem kostenlosen Konto bei OneCal Unified starten. Es gibt einen Free-Tier, ideal zum Testen und für kleine Projekte. Für den Produktionseinsatz können Sie – je nach Nutzung und Anzahl verbundener Konten – upgraden.

5. Was passiert, wenn ein Nutzer seinen Kalender trennt?

Wenn ein Nutzer trennt, sollte die App das zugehörige CalendarAccount und die Calendars aus Ihrer Datenbank entfernen. Lokale Daten können Sie ggf. zu Analysezwecken behalten – aber nicht mehr synchronisieren oder auf getrennte Kalender zugreifen.

7. Kann ich Benachrichtigungen oder Erinnerungen hinzufügen?

Ja. Sie können Erinnerungen in Ihrer App bauen oder das native Benachrichtigungssystem des verbundenen Kalenders nutzen (Google, Outlook etc.).

8. Was, wenn die API meine Anfragen wegen Rate Limits begrenzt?

Die OneCal Unified API hat eingebaute Rate Limits zur Stabilität. Wenn Sie das Limit erreichen, reduzieren Sie die Frequenz und versuchen Sie es nach kurzer Zeit erneut. Beachten Sie, dass auch die Anbieter eigene Limits haben – bei Google und Microsoft können höhere Limits beantragt werden.

9. Ist eine bidirektionale Synchronisation möglich?

Ja. Die OneCal Unified API unterstützt Two-Way-Sync: Sie können Ereignisse sowohl lesen als auch schreiben. Bei Änderungen auf Anbieter-Seite erhalten Sie Webhook-Benachrichtigungen.

10. Wie kann ich dieses Projekt deployen?

Ein Deployment zu Vercel ist einfach. Setzen Sie die Umgebungsvariablen (DATABASE_URL, ONECAL_UNIFIED_API_KEY, OAuth-Credentials etc.) in den Projekteinstellungen. Alternativ können Sie per Docker containerisieren, wenn Sie mehr Kontrolle möchten.