waynesutton/convex-best-practices

Que fait convex-best-practices ?

Bonnes pratiques pour construire des applications Convex prêtes pour la production, couvrant l'organisation des fonctions, les motifs de requête, la validation, l'utilisation de TypeScript, la gestion des erreurs et la philosophie de conception Zen de Convex.

Introduction

Ce guide rassemble les meilleures pratiques pour développer avec Convex, une plateforme de backend serverless et réactive. En suivant ces recommandations, vous créerez des applications plus robustes, maintenables et performantes.

Organisation des fonctions

• Regroupez les fonctions par domaine fonctionnel (par exemple users.ts, posts.ts) plutôt que par type (queries.ts, mutations.ts).
• Utilisez des fichiers séparés pour les mutations et les requêtes dans chaque domaine si le nombre de fonctions devient important.
• Nommez les fichiers en minuscules avec des tirets (kebab-case).
• Exportez uniquement les fonctions qui doivent être visibles publiquement (via export default pour une mutation/requête).

Motifs de requête

• Privilégiez les requêtes avec projection pour limiter les données récupérées : utilisez le deuxième paramètre de query pour spécifier les champs nécessaires.
• Évitez les N+1 requêtes en utilisant withIndex ou withField pour les recherches par index.
• Utilisez des requêtes agrégées (via aggregate) uniquement lorsque c'est nécessaire, car elles peuvent être coûteuses à grande échelle.
• Favorisez les requêtes simples et paginées avec cursor pour les listes longues.

Validation

• Validez les entrées de toutes les mutations et requêtes exposées publiquement avec Zod (ou un schéma de validation équivalent).
• Utilisez des transformateurs pour nettoyer les données (par exemple z.string().trim()).
• Gérez les erreurs de validation en retournant un objet avec un code d'erreur explicite plutôt que de les propager.
• Évitez de valider des données qui sont déjà garanties par le système (comme l'ID d'utilisateur authentifié).

Utilisation de TypeScript

• Activez strict: true dans tsconfig.json pour bénéficier de la sécurité de type maximale.
• Définissez des types explicites pour les arguments des fonctions et les retours.
• Évitez le mot-clé any ; utilisez unknown si nécessaire avec une vérification de type.
• Utilisez des types utilitaires comme Partial<T>, Pick<T>, Omit<T> pour manipuler les types sans duplication.

Gestion des erreurs

• Utilisez des codes d'erreur HTTP standard dans les mutations/requêtes (ex. 401, 404, 409, 500).
• Ne renvoyez jamais de messages d'erreur internes à l'utilisateur final ; loggez-les côté serveur.
• Pour les erreurs d'authentification et d'autorisation, utilisez convexError avec un statut HTTP approprié.
• En cas d'échec de mutation, assurez-vous que l'état de l'application reste cohérent (rollback automatique dans Convex).

Zen de Convex

La philosophie de Convex repose sur quelques principes fondamentaux :

• Simplicité : Évitez la complexité inutile. Convex gère les mises à jour en temps réel, la synchronisation et le cache. Laissez-le faire.
• Explicite : Soyez clair sur les dépendances (par exemple, les requêtes doivent importer explicitement les documents nécessaires).
• Performant : Profitez des requêtes optimisées, des caches et des mises à jour incrémentales de Convex. Évitez les calculs coûteux côté client.
• Maintenable : Organisez le code de manière logique, documentez les choix importants et testez les mutations critiques.

Ressources supplémentaires

• Documentation officielle Convex
• Exemples de code