Comment créer une application de calendrier - Guide complet

Si vous êtes un développeur chargé d’intégrer un calendrier dans votre application, ou un entrepreneur qui envisage de créer une application de calendrier, ou une application qui propose des intégrations de calendrier, cet article est fait pour vous.

Apprenons à créer une application de calendrier, à aborder chaque décision étape par étape, à choisir les meilleures technologies et à découvrir les défis ainsi que les bonnes pratiques.

Quel est le périmètre de cet article ?

Comme mentionné dans l’introduction, l’objectif de cet article est de vous aider à créer une application de calendrier complète, ou simplement à intégrer des fournisseurs de calendrier dans votre application existante, afin que les utilisateurs puissent connecter leurs calendriers et les gérer via votre application.

Cet article est également utile même si vous souhaitez intégrer des fournisseurs de calendrier sans proposer d’interface de calendrier. Des exemples seraient une application de tâches, une application de rencontres ou même une fonctionnalité qui insère un événement dans les calendriers d’un utilisateur.

Vous pouvez librement reprendre certaines parties de l’article et les utiliser dans votre base de code, y compris les choix technologiques, les API unifiées ou des extraits de code.

Vue d’ensemble de l’architecture et de la pile technologique

La plateforme que nous avons choisie pour illustrer cet exemple est le Web, car il est plus simple de la démarrer et de l’exécuter, et la communauté offre de nombreux supports pour les bibliothèques de calendrier.

Le langage de programmation que nous utiliserons est TypeScript, et le framework web est Next.js.

Voici un aperçu de la pile technique que nous allons utiliser :

• Frontend : Next.js (App Router, TypeScript)

• Backend : routes API Next.js + tRPC.

• Base de données : PostgreSQL (en utilisant Prisma comme ORM)

• APIs de calendrier : OneCal Unified Calendar API

• Hébergement : Agnostique au fournisseur, vous pouvez l’héberger sur Vercel, ou où vous êtes à l’aise.

• Authentification : OAuth2 (Google, Microsoft) via better-auth

Ci-dessous, le schéma architectural et la façon dont la pile s’articule :

Définitions :

• Client (1) : L’appareil de l’utilisateur final. L’illustration utilise un appareil mobile, mais cela pourrait être un ordinateur de bureau, un ordinateur portable, etc. (tout appareil prenant en charge les navigateurs web tels que Google Chrome). Le client est responsable du rendu du frontend Next.js, de la gestion des interactions utilisateur et de la communication avec le backend via des requêtes HTTPS sécurisées.

• Serveur Web (2) : Le serveur web héberge et sert l’interface utilisateur, une application web Next.js (App Router). Il délivre un HTML, CSS et JavaScript optimisés au client et fournit le rendu côté serveur (SSR) ainsi que la régénération statique incrémentale (ISR) pour des performances rapides et des avantages SEO.

• API Next.js (3) : L’API Next.js sert de couche backend, implémentée à l’aide des routes API et de tRPC au sein de la même application Next.js. Elle fonctionne comme le hub central reliant le frontend, la base de données et les intégrations externes comme OneCal Unified Calendar API. Contrairement aux endpoints REST traditionnels, tRPC permet une communication de bout en bout, typée, entre le frontend et le backend sans nécessiter la définition d’un schéma d’API séparé. Cela signifie que le client peut appeler directement des procédures backend, avec une inférence complète des types TypeScript. Cela aide à améliorer la vitesse de développement et à réduire les erreurs à l’exécution.

• PostgreSQL (4) : La base de données PostgreSQL stocke toutes les données persistantes de l’application, y compris les utilisateurs, les sessions, les comptes de calendrier connectés, etc. Elle constitue la source de vérité pour toutes les données liées aux utilisateurs et aux états de synchronisation. Avec Prisma comme couche ORM, le schéma est proprement mappé à la base, ce qui rend les migrations et les requêtes faciles à gérer.

• OneCal Unified Calendar API (5) : OneCal Unified Calendar API est l’API que nous utilisons pour intégrer tous les fournisseurs de calendrier via une API standardisée. OneCal Unified nous facilite l’intégration de tous les fournisseurs de calendrier, sans avoir à coder des implémentations séparées, gérer des interfaces de données différentes, maintenir de multiples intégrations ou subir les changements d’API. Notre API communique avec OneCal Unified Calendar API en envoyant la clé d’API et les calendriers sur lesquels nous voulons effectuer des opérations (CRUD d’événements, de calendriers, et plus), quel que soit le fournisseur. En retour, OneCal communique avec les fournisseurs de calendrier puis renvoie la réponse dans un format standardisé pour tous les fournisseurs.

Notez que le Serveur Web (2) et l’API Next.js (3) peuvent être hébergés sur le même serveur (en utilisant Vercel, Docker, etc.), mais ils sont séparés ici pour illustrer visuellement qu’il existe un serveur d’interface utilisateur et un serveur d’API, même s’ils se trouvent tous deux dans la même base de code Next.js et sont généralement hébergés sur le même serveur.

Concevoir le modèle de données

Après avoir expliqué l’architecture et la pile technologique, il est temps de définir notre modèle de données. Nous utiliserons Prisma comme ORM de préférence.

Ce schéma Prisma définit la structure de données pour une application de calendrier basique qui prend en charge l’authentification des utilisateurs, les connexions de comptes de calendrier (Google, Microsoft) et la synchronisation des événements via une API unifiée.

Les modèles les plus importants sont :

1. User

Représente un utilisateur final de l’application. Chaque utilisateur peut avoir plusieurs sessions, des comptes connectés (OAuth) et des comptes de calendrier. Des champs comme email, name et onboardingCompletedAt aident à suivre le profil et l’état d’onboarding.

2. CalendarAccount

Représente un compte de calendrier externe lié (par ex., un compte Google ou Microsoft). Il stocke le provider, l’email et le status (actif ou expiré). Chaque CalendarAccount appartient à un User et peut contenir plusieurs entrées Calendar.

3. Calendar

Représente un calendrier individuel (comme « Travail », « Personnel » ou « Famille ») au sein d’un compte lié. Il inclut des champs d’affichage tels que name, color, timezone, et des drapeaux comme isPrimary ou isReadOnly. Chaque calendrier est lié à la fois à un User et au CalendarAccount dont il provient.

4. Account

Gère les données du fournisseur OAuth (Google ou Microsoft). Il stocke les jetons d’accès et d’actualisation, les dates d’expiration des jetons et les informations de portée, utilisées pour l’authentification et la synchronisation des calendriers.

5. Session

Suit les sessions de connexion actives des utilisateurs. Contient des champs tels que token, expiresAt, ipAddress et userAgent pour gérer et sécuriser les sessions actives.

6. Verification

Utilisé pour des vérifications ponctuelles, telles que les liens magiques de connexion par e-mail ou les codes d’authentification sans mot de passe. Il stocke des identifiants temporaires et des temps d’expiration.

7. Enums

• CalendarAccountProvider : Définit les fournisseurs pris en charge (GOOGLE, MICROSOFT).

• CalendarAccountStatus : Indique si un compte connecté est ACTIVE ou EXPIRED.

Le diagramme ER de la base de données :

Veuillez ouvrir le fichier schema.prisma dans notre dépôt GitHub pour voir le schéma complet de la base de données, y compris les types et les relations.

Construire le Backend

Comme mentionné, nous utiliserons les routes API de Next.js pour construire l’API, car il est très pratique d’avoir l’API et l’UI dans la même base de code et hébergées sur le même serveur. Cela signifie que vous pouvez exécuter l’UI et l’API simultanément.

Mettre en place l’authentification

Nous utiliserons better-auth comme framework d’authentification. Better Auth rend l’authentification très simple et fluide. Veuillez suivre le guide Better Auth sur comment intégrer Better Auth avec Next.js, car les étapes sont presque identiques à ce guide. Vous pouvez également consulter le fichier d’auth dans notre dépôt pour en savoir plus.

Configurer OneCal Unified Calendar API pour communiquer avec tous les fournisseurs de calendrier

Le principal point douloureux lors de la création d’une application de calendrier ou de l’intégration de calendriers dans une application ou une fonctionnalité existante est la gestion des API spécifiques à chaque fournisseur. Cela a un coût en temps, car il faut apprendre chaque API séparément, gérer des structures de données, requêtes, réponses différentes, et plus encore. De plus, il faudrait construire une intégration séparée pour chaque fournisseur et maintenir ces intégrations une fois le développement terminé.

Une excellente solution à ce problème consiste à utiliser une API de calendrier unifiée qui nous aide à intégrer tous les fournisseurs de calendrier via une API standardisée. Dans cet exemple, nous utiliserons la OneCal Unified Calendar API.

Pour commencer avec OneCal Unified, suivez ces étapes :

1. La première étape consiste à créer un compte OneCal Unified et à ouvrir un compte gratuit.

   

2. Après votre inscription, activez les fournisseurs de calendrier que vous souhaitez intégrer. Nous recommandons d’activer Google Calendar et Outlook, afin de bien comprendre la puissance d’un produit d’API de calendrier unifiée. Notez que vous n’avez pas besoin de créer un client Google ou Microsoft, car pour le bac à sable et le développement vous pouvez utiliser le client Google de OneCal Unified, ce qui vous permet de connecter des comptes Outlook ou Google Calendar à votre application.

   

3. Créez une clé d’API et stockez-la dans la variable d’environnement ONECAL_UNIFIED_API_KEY

   

Construire le client OneCal Unified API

Après avoir configuré OneCal Unified Calendar API et récupéré la clé d’API, il est temps de construire le client qui interagit avec OneCal Unified Calendar API :

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}`,
  );
}

Vous pouvez trouver les types du client et d’autres classes pertinentes à cet emplacement GitHub.

Le diagramme de séquence explique comment l’application de calendrier d’exemple interagit avec OneCal Unified Calendar API pour offrir une intégration transparente avec tous les fournisseurs de calendrier.

Créer les routes de l’API

Après avoir configuré le client OneCal Unified Calendar API, nous pouvons créer les routes API pour gérer les comptes de calendrier et les événements de calendrier. Notez que nous n’avons pas besoin de créer explicitement des API de session, car nous nous appuyons sur BetterAuth à cette fin.

L’API contient des définitions de routes pour :

• Comptes de calendrier : route qui expose des méthodes HTTP pour lister tous les comptes de calendrier et supprimer un compte de calendrier par ID.

• Événements de calendrier : route qui expose des méthodes HTTP pour effectuer des opérations CRUD sur les événements de calendrier.

• Calendriers : route qui expose des méthodes HTTP pour mettre à jour les calendriers.

Une définition de route en tRPC ressemblerait à ceci : ⁠

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,
      );
    }),
});

La méthode getCalendarEvent provient du client OneCal Unified Calendar API que nous avons construit ci-dessus.

Veuillez ouvrir le répertoire des routes API dans notre dépôt GitHub pour obtenir le contenu de chaque route API, car le coller dans cet article serait assez répétitif.

Construire le Frontend

Le frontend sera construit avec Next.js + TypeScript. Lors de la création d’une application de calendrier, le composant le plus important est… vous l’avez deviné : le calendrier.

D’après notre expérience, les meilleures bibliothèques d’interface de calendrier pour Next.js et React sont :

• react-big-calendar

• @fullcalendar/react

Pour cet exemple, nous avons choisi d’utiliser react-big-calendar en raison de sa simplicité d’utilisation avec Next.js, mais gardez à l’esprit que nous recommandons d’utiliser fullcalendar dans les applications en production, car il est plus personnalisable et dispose d’un plus large support communautaire.

En outre, fullcalendar est disponible dans d’autres bibliothèques comme Zvelte, Vue.js, etc.

Utilisation de react-big-calendar :

      <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;
          }
        }}
      />

Pour voir l’implémentation complète, ouvrez le chemin src/app/(protected)/(calendar) dans le dépôt GitHub. Le composant principal est la page events-calendar.tsx. Vous trouverez également des composants pour modifier des événements (y compris récurrents), supprimer des événements et créer des événements.

Voici à quoi ressemble le calendrier :

L’utilisateur peut cliquer sur une cellule et créer un événement :

Lorsque l’utilisateur clique sur un événement existant, il a la possibilité de le supprimer ou de le modifier.

Quand l’événement est récurrent, l’utilisateur peut choisir de modifier l’instance sélectionnée ou toute la série.

Voici à quoi ressemble l’interface d’édition d’un événement :

L’interface nécessite encore du polissage, mais nous ne voulions pas créer une application de calendrier parfaite : le but est de construire une application fonctionnelle et une intégration de calendrier. Vous pourrez peaufiner les styles pour qu’ils correspondent à votre marque.

Défis courants et bonnes pratiques

Créer une application de calendrier ou ajouter des fonctionnalités de calendrier n’est pas toujours simple. Même si la fonctionnalité principale semble simple, de nombreux petits détails peuvent poser des problèmes par la suite. Ci-dessous se trouvent quelques défis courants que vous pourriez rencontrer, ainsi que des bonnes pratiques pour les gérer.

1. Fuseaux horaires

Défi :

Les événements peuvent apparaître à la mauvaise heure lorsque les utilisateurs sont dans des fuseaux horaires différents.

Bonne pratique :

• Enregistrez toujours les heures en UTC dans votre base de données. Cela exclut les événements de calendrier, car nous ne recommandons pas de stocker les événements de calendrier dans votre base. Lorsque vous récupérez des événements via l’API du fournisseur de calendrier, vous devriez également pouvoir recevoir le fuseau horaire de l’événement depuis l’API.

• Convertissez en heure locale de l’utilisateur uniquement lors de l’affichage côté frontend.

• Utilisez une bibliothèque comme date-fns-tz ou luxon pour gérer les conversions horaires. Dans cet exemple, nous utilisons date-fns et date-fns-tz.

2. Événements récurrents

Défi :

Gérer les événements qui se répètent (quotidien, hebdomadaire, mensuel) peut être complexe, notamment lorsque les utilisateurs souhaitent modifier ou supprimer une seule instance.

Bonne pratique :

• Laissez l’utilisateur choisir s’il veut mettre à jour un seul événement ou toute la série. Cette pratique est suivie par Google Calendar, Outlook et de nombreux autres clients de calendrier. Nous l’avons également adoptée dans notre application Calendrier.

3. Expiration des jetons OAuth

Défi :

Les utilisateurs peuvent perdre la connexion à leurs calendriers si les jetons expirent ou sont révoqués.

Bonne pratique :

• Stockez en toute sécurité les jetons d’actualisation afin d’obtenir automatiquement de nouveaux jetons d’accès.

• Gérez gracieusement les erreurs de jeton et invitez les utilisateurs à reconnecter leurs comptes si nécessaire.

4. Garder les données synchronisées

Défi :

Les données de calendrier peuvent devenir obsolètes si vous ne les récupérez qu’une seule fois.

Bonne pratique :

• Utilisez les webhooks de OneCal Unified Calendar API pour rester informé lorsque des événements changent.

• Nous vous recommandons de récupérer les événements auprès des fournisseurs de calendrier lorsque l’utilisateur interagit avec l’application de calendrier. Veuillez ne pas stocker les événements dans votre base de données, car les maintenir synchronisés avec tous les fournisseurs peut être un défi difficile. En outre, stocker les événements de calendrier dans la base n’est pas si bénéfique, étant donné que vous pouvez récupérer les événements de tous les fournisseurs en utilisant OneCal Unified Calendar API.

5. Gestion des erreurs d’API

Défi :

Les API externes (Google, Outlook, iCloud) peuvent renvoyer des erreurs, des limites de taux ou des défaillances temporaires.

Bonne pratique :

• Ajoutez une logique de nouvelle tentative pour les erreurs temporaires (l’utilisation de temporisateurs est une option viable).

• Respectez les limites de taux de l’API et patientez si nécessaire. Notez que OneCal Unified Calendar API a des limites de taux, tout comme les fournisseurs de calendrier tels que Google Calendar / Outlook Calendar.

• Journalisez toutes les requêtes échouées pour faciliter le débogage.

6. Calendriers volumineux

Défi :

Certains utilisateurs ont des centaines voire des milliers d’événements, ce qui peut ralentir l’application.

Bonne pratique :

• Chargez les événements par pages (utilisez la pagination). La pagination est prise en charge par tous les principaux fournisseurs de calendrier. Si vous utilisez OneCal Unified Calendar API, vous remarquerez que tous les résultats sont paginés, vous n’aurez donc pas ce problème.

• Ne récupérez que les événements de l’intervalle de dates visible (par exemple, cette semaine ou ce mois). D’une manière générale, c’est une bonne pratique d’obtenir juste ce dont vous avez besoin. Une application de calendrier a une vue jour, semaine, mois et année. Récupérez les événements en fonction de l’intervalle.

7. Confidentialité et sécurité des utilisateurs

Défi :

Les données de calendrier incluent souvent des informations privées.

Bonne pratique :

• Ne stockez pas les événements de calendrier dans votre base de données. Le stockage de la clé d’accès et de la clé d’actualisation devrait suffire.

• Chiffrez les jetons et les champs sensibles dans votre base de données. Nous recommandons de chiffrer votre base au repos. Des services comme AWS RDS proposent le chiffrement des données par défaut.

• Permettez aux utilisateurs de déconnecter leurs comptes de calendrier à tout moment. C’est très important, car si vous ne permettez pas aux utilisateurs de déconnecter ou supprimer leurs calendriers, ils révoqueront l’accès directement depuis la gestion de leur compte Google.

FAQ

1. Puis-je utiliser un autre backend au lieu des routes API de Next.js ?

Oui. Bien que cet exemple utilise des routes API Next.js avec tRPC, vous pouvez utiliser n’importe quel framework backend comme Nest.js, Express ou Django. L’essentiel est que votre backend communique avec OneCal Unified Calendar API via des requêtes HTTPS. La structure de la base et la logique d’API resteront globalement les mêmes.

2. Dois-je créer mes propres applications développeur Google ou Microsoft ?

Non, vous pouvez utiliser les clients Google et Microsoft de OneCal Unified pendant le développement. Quand votre application passera en production, vous pourrez créer vos propres identifiants OAuth2 si vous souhaitez un contrôle et un branding complets pour vos utilisateurs.

3. Puis-je utiliser une autre base de données que PostgreSQL ?

Oui. Prisma prend en charge de nombreuses bases de données telles que MySQL, SQLite et MongoDB. Nous avons choisi PostgreSQL parce qu’il est fiable, évolutif et facile à mettre en place en production. Vous pouvez également choisir toute autre base et tout autre ORM, selon votre pile technique.

4. OneCal Unified Calendar API est-elle gratuite ?

Vous pouvez commencer gratuitement en créant un compte sur OneCal Unified. Il existe une formule gratuite idéale pour les tests et les petits projets. Pour un usage en production, vous pouvez passer à une formule supérieure selon votre utilisation et le nombre de comptes connectés.

5. Que se passe-t-il si un utilisateur déconnecte son calendrier ?

Lorsqu’un utilisateur se déconnecte, l’application doit supprimer le CalendarAccount et les Calendars correspondants de votre base de données. Vous pouvez conserver des données locales pour l’analytique si nécessaire, mais assurez-vous de ne plus synchroniser ni accéder aux calendriers déconnectés.

7. Puis-je ajouter des notifications ou des rappels ?

Oui. Vous pouvez construire des rappels dans votre application ou utiliser le système de notifications natif du calendrier connecté (Google, Outlook, etc.).

8. Que faire si l’API limite le taux de mes requêtes ?

OneCal Unified API inclut des limites de taux intégrées pour la stabilité. Si vous atteignez la limite, attendez et réessayez après un court délai. Notez que les fournisseurs de calendrier auront également leurs propres limites au niveau des applications. Ces limites peuvent varier et Google comme Microsoft permettent de demander une limite plus élevée si nécessaire.

9. Est-il possible de synchroniser les événements dans les deux sens ?

Oui. OneCal Unified API prend en charge la synchronisation bidirectionnelle, ce qui signifie que vous pouvez à la fois lire et écrire des événements dans les calendriers connectés. Vous recevrez des notifications webhook lorsque des changements se produisent côté fournisseur.

10. Comment puis-je déployer ce projet ?

Vous pouvez déployer facilement l’application sur Vercel. Assurez-vous de définir vos variables d’environnement (DATABASE_URL, ONECAL_UNIFIED_API_KEY, identifiants OAuth, etc.) dans les paramètres de votre projet. Vous pouvez également la containeriser avec Docker si vous préférez davantage de contrôle.