Forem: Virgile RIETSCH

Comment bien gérer les erreurs avec Remix ? (ErrorBoundary)

Virgile RIETSCH — Sat, 25 May 2024 09:59:49 +0000

As-tu déjà eu des erreurs Javascript en production ? Pire encore, as-tu reçu l'appel d'un client, qui se plaint d'avoir reçu un message d'erreur ?
Tu perds de la crédibilité.

Heureusement, il existe le composant ErrorBoundary qui permet d'afficher un composant d'erreur, respectant le thème du site et ton Design System.

Avant d'utiliser ErrorBoundary

Tu retrouves un message d'erreur générique incompréhensible. Difficile de comprendre ce qui a pu se passer, et tu vas prendre du temps à réparer le bug. De plus, ton site est inutilisable en l'état. La navigation de ton utilisateur a été coupée brutalement.

Après avoir mis en place ErrorBoundary

Tu améliores l'expérience utilisateur. Tu réduis l'impact de l'erreur à l'endroit où elle a été déclenchée. Cela permet au développeur de vite résoudre le problème, car il sait exactement de quel fichier il s'agit.

Dans Remix, on utilise le composant ErrorBoundary, qui va remplacer le composant ayant déclenché l'erreur.

Tu retrouves cet exemple et davantage d'information dans la documentation de Remix concernant l'error handling

Pour améliorer l'expérience utilisateur (UX), il est recommandé d'offrir une explication claire dans le message d'erreur, comme expliqué dans la figure ci-dessous (Source).

Un message d'erreur idéal :

rassure le client
explique la raison du problème
offre une marche à suivre pour arranger les choses (contacter le support)

Qu'est-ce que le composant ErrorBoundary ?

C'est une librairie Javascript, disponible sur NPM sous le nom de react-error-boundary. Elle est téléchargée plus de 3,7 millions de fois par semaine.

Pour l'utiliser dans une application React standard, il suffit de la télécharger dans ton projet :

npm install react-error-boundary

Ensuite, tu l'utilises dans un composant React. Elle va englober le composant qui risque de déclencher une erreur, et afficher un composant fallback à la place.

import { ErrorBoundary } from 'react-error-boundary';

<ErrorBoundary fallback={<div>Something went wrong</div>}>
    <ExampleApplication />
</ErrorBoundary>;

Cet exemple montre deux composants :

Le composant parent ErrorBoundary, qui prend un children (le composant enfant) et une propriété fallback (affichant le composant d'erreur)
Le composant enfant ExampleApplication. En cas d'erreur de ce dernier, l'erreur ne va pas remonter à la racine de l'application. À la place, l'erreur va afficher le composant fallback.

Il y a une deuxième manière d'utiliser ce composant, offrant plus de contrôle et une meilleure UX.

import { ErrorBoundary } from 'react-error-boundary';

function fallbackRender({ error, resetErrorBoundary }) {
    // Call resetErrorBoundary() to reset the error boundary and retry the render.

    return (
        <div role='alert'>
            <p>Something went wrong:</p>
            <pre style={{ color: 'red' }}>{error.message}</pre>
        </div>
    );
}

<ErrorBoundary
    fallbackRender={fallbackRender}
    onReset={(details) => {
        // Reset the state of your app so the error doesn't happen again
    }}
>
    <ExampleApplication />
</ErrorBoundary>;

La propriété fallbackRender accepte une fonction fléchée, nous permettant de récupérer deux arguments :

Les informations sur l'erreur qui a été déclenchée
Une fonction permettant de ré-effectuer un rendu du composant. Déclencher cette fonction permet d'annuler l'erreur, et d'afficher le composant enfant.

Généralement, on laisse l'utilisateur appeler cette méthode resetErrorBoundary. Plus haut, par exemple en utilisant le bouton Try Again.

Mais cet article ne se concentre pas sur ce composant très utile.

Si tu utilises Remix, tu n'as même pas besoin de l'utiliser.

Il est intégré directement dans la librairie !

Comment gérer tes erreurs avec Remix

Pour déclencher une erreur dans ton application Remix, il te suffit d'ajouter l'instruction throw new Error('bam') sur n'importe quelle route active.

Ce qui affiche ceci :

Cette erreur n'est pas claire du tout. Et elle rend ton application inutilisable pour les clients : Ils ne peuvent pas accéder à une autre page depuis l'interface.

De plus, cela ne t'aide pas à connaître la raison de l'erreur : elle pourrait être déclenchée par n'importe quoi.

Comment faire ? Il suffit d' exporter un composant nommé ErrorBoundary dans ton application Remix. Commence par l'importer dans le fichier root.tsx, se situant dans le dossier app/routes de ton projet Remix.

Le composant ErrorBoundary (Remix)

Le composant ErrorBoundary est une convention de Remix (au même titre que les méthodes loader et action). Exporter un composant nommé "ErrorBoundary" dans n'importe quelle route indique à Remix qu'en cas d'erreur, il doit afficher son contenu, et ne pas propager l'erreur plus haut.

Prenons par exemple l'export ci-dessous :

export function ErrorBoundary() {
    const error = useRouteError();
    let errorMessage = 'Une erreur inattendue est survenue';

    if (error instanceof Error) {
        errorMessage = error.message;
    }

    return <div>{errorMessage}</span>;
}

Après avoir ajouté ces quelques lignes, notre application ressemble à ça :

On avait rajouté la ligne throw new Error('bam');. Au lieu d'afficher l'erreur en rouge, sans design, notre composant ErrorBoundary est affiché.

Cela nous apporte quelques bénéfices :

L'erreur ne se propage pas au dessus (on y revient un peu plus bas)
On peut designer notre message d'erreur, expliquer au client ce qui s'est passé, et lui indiquer la marche à suivre
En bonus, on peut sauvegarder cette erreur avec un outil comme Sentry, ou l'envoyer par email pour être prévenu si jamais elle est déclenchée en production.

Les erreurs ne remontent pas

React utilise un système de composants, avec des balises imbriquées. Ce qui donne une hiérarchie avec des "parents" et des "enfants".

Avec Remix, il est possible d'implémenter des routes imbriquées. Cela signifie qu'il est possible d'avoir plusieurs routes actives en même temps.

C'est ce que nous montre l'image, que nous avions vu au dessus :

Cette image représente une route imbriquée. Quatres routes sont actuellement actives :

La route root principale. C'est notre composant d'entrée, cette route est rendue sur toutes les routes. La route root affiche la barre latérale, sur le côté gauche.
La route sales (on la voit comme premier segment dans l'URL) affiche le titre de la page "Sales", ainsi qu'une barre de navigation horizontale.
La route invoices (on retrouve son segment dans l'URL) est "enfant" de la route Sales, et affiche les statistiques globales, la barre jaune et verte ainsi que le tableau de factures
La route dynamique 102000 (où 102000 représente une id de facture) est imbriquée dans invoices (encore une fois, on le constate grâce au segment d'URL final). C'est le dernier enfant de cette hiérarchie, l'enfant le plus bas. Et il est en erreur.

On peut symboliser cette vue d'une autre manière :

export default function Page () {
return (<Sales>
      <Invoices>
        <Invoice id="102000"/>
      </Invoices
  </Sales>)
}

Chaque imbrication représente un enfant dans notre composant. Et le composant ErrorBoundary empêche notre erreur de remonter plus haut.

Ce qui est représenté par l'image ci-dessus, au final, est un message d'erreur qui a empêché une erreur déclenchée dans le composant Invoice de remonter plus haut.

C'est un peu comme s'il s'était passé la chose suivante :

export default function Page() {
    return (
        <Sales>
            <Invoices>
                <ErrorBoundary fallback={<Error message='Something went wrong' />}>
                    <Invoice id='102000' />
                </ErrorBoundary>
            </Invoices>
        </Sales>
    );
}

Remix a remplacé le composant Invoice par un composant Error, car ce fichier était protégé par une fonction ErrorBoundary.

En ajoutant ce composant sur notre route imbriquée, nous améliorons considérablement l'expérience de nos utilisateurs. De plus, nos développeurs identifient plus rapidement le problème, car le composant en erreur est au plus bas dans la hiérarchie.

Héberge des fichiers avec Remix

Virgile RIETSCH — Mon, 20 May 2024 07:05:54 +0000

Dans cet article, nous allons implémenter ensemble un formulaire permettant d'héberger des fichiers (images, vidéos, PDFs...). Nous utilisons le framework Remix et son puissant système de routing pour y parvenir.

Vous pouvez aussi consulter ce guide au format vidéo sur YouTube.

Voici la commande pour initialiser un nouveau projet Remix :

npx create-remix@latest

Comment héberger un formulaire avec Remix ?

On a besoin de trois éléments :

un fichier à héberger
un input de type file pour le sélectionner et l'envoyer au serveur
un serveur pour le sauvegarder et le servir sur une route

Un fichier à héberger

Voici une image. Je vous laisse la télécharger. C'est le document que nous allons héberger ensemble.

Un input de type file pour envoyer le fichier au serveur

Nous allons ajouter un fichier dans le dossier app/routes, nommé file. Dedans, nous allons exporter par défaut un composant React (ce sera notre vue).

import { Form } from '@remix-run/react';

export function File() {
    return (
        <Form
            method='POST'
            className='mt-8 flex flex-col gap-2 w-full items-center'
        >
            <input type='file' name='file' />
            <button type='submit'>Soumettre</button>
        </Form>
    );
}

Notez l'utilisation du composant Form de Remix. Bien que l'hébergement des fichiers fonctionne avec un formulaire classique, il est recommendé de l'utiliser.

Un serveur pour sauvegarder le fichier et le servir aux utilisateurs

Dans l'article 6 Routes à connaître si tu utilises Remix (guide complet), nous avons vu ensemble qu'il nous suffit d'ajouter une fonction à notre fichier pour ajouter une logique côté serveur.

Comme le formulaire effectue un POST, nous allons ajouter une fonction nommée action dans notre composant, et nous allons l'exporter.

import type { ActionFunctionArgs } from '@remix-run/node';
import { Form } from '@remix-run/react';

export const action = async ({ request }: ActionFunctionArgs) => {
    // Nous devons sauvegarder le fichier à cet endroit
    return null;
};

export function File() {
    return (
        <Form
            method='POST'
            className='mt-8 flex flex-col gap-2 w-full items-center'
        >
            <input type='file' name='file' />
            <button type='submit'>Soumettre</button>
        </Form>
    );
}

Il ne nous reste plus qu'à coder la logique dans notre action et nous avons terminé ! N'est-ce pas ?

Pas vraiment. Avez-vous entendu parlé de la propriété encType ?

La propriété de formulaire 'encType'

Version courte

Il faut rajouter la propriété encType à notre formulaire.

import type { ActionFunctionArgs } from '@remix-run/node';
import { Form } from '@remix-run/react';

export const action = async ({ request }: ActionFunctionArgs) => {
    // Nous devons sauvegarder le fichier à cet endroit
    return null;
};

export function File() {
    return (
        <Form
            method='POST'
            encType='multipart/form-data'
            className='mt-8 flex flex-col gap-2 w-full items-center'
        >
            <input type='file' name='file' />
            <button type='submit'>Soumettre</button>
        </Form>
    );
}

Pourquoi rajouter la propriété encType ?

Je ne connaissais pas cette propriété avant d'en avoir besoin. Par défaut, la propriété encType (ou type d'encodage) prend comme valeur application/x-www-form-urlencoded. Mais il en existe deux autres.

Voici la définition sur MDN

Lorsque la valeur de l'attribut method est post, cet attribut définit le type MIME qui sera utilisé pour encoder les données envoyées au serveur. C'est un attribut énuméré qui peut prendre les valeurs suivantes :

application/x-www-form-urlencoded: la valeur par défaut si l'attribut n'est pas défini

multipart/form-data : la valeur utilisée par un élément input avec l'attribut type="file".

text/plain, correspondant au type MIME éponyme et utilisé à des fins de débogage.

Nous utilisons un input de type file. Nous avons donc besoin de rajouter la propriété encType='multipart/form-data' pour envoyer notre fichier au format binaire.

Nous avons terminé l'implémentation côté client ! Le reste se passe côté serveur.

Sauvegarder un fichier côté serveur

Pour pouvoir sauvegarder notre fichier et la servir à nos utilisateurs, nous allons devoir

l'extraire du FormData avec les API de Remix unstable_createFileUploadHandler et unstable_parseMultipartFormData
(Bonus) Valider le formData avec Zod et Conform
(Bonus) Renommer le fichier et lui donner un identifiant unique
Servir le fichier aux utilisateurs (le rendre disponible à l'URL localhost:3000/files/image.png

Extraire le fichier depuis le FormData

Nous souhaitons conserver le document sur notre serveur. Pour ce faire, nous allons utiliser la méthode
unstable_createFileUploadHandler.

Cette méthode prend un objet d'options en argument. Voici les options que nous allons utiliser :

maxPartSize pour définir la taille max du fichier en bytes.
directory pour définir le dossier de sauvegarde du document

import {
    unstable_createFileUploadHandler,
    unstable_parseMultipartFormData,
    type ActionFunctionArgs,
} from '@remix-run/node';
import { Form } from '@remix-run/react';

export const action = async ({ request }: ActionFunctionArgs) => {
    const formData = await unstable_parseMultipartFormData(
        request,
        unstable_createFileUploadHandler({
            maxPartSize: 1024 * 1024 * 10, // 10MB
            directory: './uploads',
        })
    );
    const file = formData.get('file') as File; // 👈 notre fichier au format Buffer
    console.log(file.name); // 👈 Le nom du fichier pour pouvoir le retrouver sur le serveur
    return null;
};

export function File() {
    return (
        <Form
            method='POST'
            encType='multipart/form-data'
            className='mt-8 flex flex-col gap-2 w-full items-center'
        >
            <input type='file' name='file' />
            <button type='submit'>Soumettre</button>
        </Form>
    );
}

Enregistrer le fichier sur le disque dur serveur

Au moment de récupérer le fichier, ligne 16, le fichier a déjà été enregistré dans le dossier uploads. Pour avoir plus de contrôle sur la sauvegarde de ce fichier, je préfère utiliser la méthode
unstable_createMemoryUploadHandler. Cela nous permet d'enregistrer nous-même le fichier récupéré ligne 17 (on peut ensuite l'envoyer sur AWS S3 ou un autre service ...)

import {
    unstable_createMemoryUploadHandler,
    unstable_parseMultipartFormData,
    type ActionFunctionArgs,
} from '@remix-run/node';
import { Form } from '@remix-run/react';
import { saveVideoToLocal } from '~/videos.server';

export const action = async ({ request }: ActionFunctionArgs) => {
    const formData = await unstable_parseMultipartFormData(
        request,
        unstable_createMemoryUploadHandler({
            maxPartSize: 1024 * 1024 * 10, // 10MB
        })
    );
    const file = formData.get('file') as File; // 👈 notre fichier au format Buffer
    console.log(file.name); // 👈 Le nom du fichier pour pouvoir le retrouver sur le serveur
    // mark
    const { name } = await saveVideoToLocal({ videoFile: file }); // 👈 On sauvegarde le fichier sur le serveur
    return { name };
};

export function File() {
    return (
        <Form
            method='POST'
            encType='multipart/form-data'
            className='mt-8 flex flex-col gap-2 w-full items-center'
        >
            <input type='file' name='file' />
            <button type='submit'>Soumettre</button>
        </Form>
    );
}

export const saveVideoToLocal = async ({ videoFile }: { videoFile: File }) => {
    const originalName = new Date().toISOString() + videoFile.name;
    const baseDirectory = join(process.cwd(), './uploads');

    const filePath = join(baseDirectory, originalName);
    const arrayBuffer = await videoFile.arrayBuffer();
    const arrayBufferView = new Uint8Array(arrayBuffer);
    const fileExists = checkIfFileExists({
        filePath,
    });
    if (fileExists) {
        throw new Error('Le fichier existe déjà ...');
    }
    await access(baseDirectory);
    await writeFile(filePath, arrayBufferView);
    return { name: originalName };
};

Servir le fichier aux utilisateurs

Pour rendre accessible nos fichiers hébergés (par exemple à l'URL localhost:3000/file/image.jpeg, nous avons besoin de :

Créer une nouvelle route
Vérifier que le fichier existe
Le renvoyer en fonction de son mimetype (si c'est un JPEG, la réponse sera différente par rapport au format mp4)

Nous allons créer un nouveau fichier nommé file.$filename.tsx dans le dossier app/routes.

Pour ce faire, nous devons également installer la librairie mime. Les autres librairies fs et path sont natives à l'environnement NodeJS.

import { LoaderFunctionArgs } from '@remix-run/node';
import { readFileSync } from 'fs';
import mime from 'mime';
import { join } from 'path';

export const loader = async ({ params }: LoaderFunctionArgs) => {
    const filename = params.filename;
    if (!filename) {
        // 👈 On vérifie que le nom du fichier est bien fourni
        throw new Error('No filename provided');
    }

    const filePath = join(process.cwd(), './uploads', filename); // 👈 On construit le chemin absolu du fichier
    const fileContent = readFileSync(filePath); // 👈 On lit le fichier
    const mimeType = mime.getType(filePath); // 👈 On récupère le type MIME du fichier

    console.log({ mimeType, filename, filePath, fileContent });
    return new Response(fileContent, {
        // 👈 On renvoie le fichier
        headers: {
            'Content-Type': mimeType || 'application/octet-stream', // 👈 On renvoie le type MIME du fichier,
        },
    });
};

Conclusion

Conclusion
Dans cet article, nous avons vu comment implémenter un formulaire d'upload de fichiers dans Remix. Nous avons utilisé le composant Form de Remix et les API unstable_createFileUploadHandler et unstable_parseMultipartFormData pour gérer le transfert de fichiers. Nous avons également vu comment sauvegarder les fichiers sur le serveur et les servir aux utilisateurs.

Développe et valide un formulaire avec Remix

Virgile RIETSCH — Sun, 18 Feb 2024 10:06:07 +0000

Votre lead dev vous demande d'améliorer l'UX du formulaire de contact pour qu'il soit plus explicite dans l'affichage de ses erreurs. Il est vrai que l'UX est importante, même en tant que développeur. J'aime personnellement savoir quel champ a posé problème lorsque j'envoie un formulaire. Et les utilisateurs aussi : ils peuvent gagner en autonomie et nous expliquer l'erreur qu'ils ont rencontré.

Dans cet article, nous allons implémenter étape par étape un formulaire avec le framework Remix. D'abord sans librairie externe. Puis nous allons l'améliorer peu à peu en ajoutant Zod, puis Conform.

Cet article existe également au format vidéo sur YouTube.

Commençons par faire simple.

Implémentation d'un formulaire basique avec Remix

Avant d'installer quoi que ce soit, nous allons implémenter un formulaire HTML basique.

Nous allons d'abord :

instantier un nouveau projet Remix avec la commande npx create-remix@latest
npm install pour installer les dépendances
npm run dev pour lancer le serveur de développement

Ensuite, nous allons supprimer le contenu du fichier app/routes/_index.tsx et le remplacer par un formulaire simple.

export default function Index() {
    return (
        <form>
            <input type='text' />
            <button>S&apos;inscrire</button>
        </form>
    );
}

Actuellement, nous avons implémenté un formulaire HTML qui contient un input et un button. Il ne nous sera pas très utile dans cet état.
Ce formulaire utilise la méthode GET par défaut. Cela signifie que chacune des données présente dans l'input seront visibles dans l'URL lors de la soumission (sous forme de paramètres d'URL). De plus, l'input ne possède pas de propriété name. Sa valeur ne sera pas récupérée. Elle a besoin d'avoir un nom pour être identifiée. (comme la paire clé-valeur dans un object)

Cet article va uniquement utiliser un formulaire POST, qui est idéal pour envoyer des données sensibles comme des adresses email.

Rajoutons des attributs 'form.POST' et 'input.name'

Il manque des attributs à notre formulaire:

la méthode POST de notre formulaire JSX
la propriété name à notre input (qui prend également la valeur name

export default function Index() {
    return (
        <form method='POST'>
            <input type='text' name='name' />
            <button type='submit'>S&apos;inscrire</button>
        </form>
    );
}

Essayons de soumettre notre formulaire !

405 Method Not Allowed

L'erreur 405 Method Not Allowed apparaît. Mais nous n'avons pas fait d'erreur au niveau de l'implémentation du formulaire. Cette erreur nous explique qu'il faut maintenant ouvrir un API endpoint à cette URL. Ce que j'appelle API endpoint est en réalité une déclaration de route API, comme avec Express.

La page API Routes (documentation de Remix) nous explique que les fichiers de type route (dans le dossier routes) sont leur propre API.

Pour mieux comprendre, regardons la page Fullstack Data Flow de la doc.

Le schéma ci-dessus représente l'ordre d'exécution des méthodes de Remix :

La méthode loader (facultative) s'éxecute en premier lors d'un chargement de page. Exécuté côté serveur, on peut charger les données nécessaires avant d'afficher la vue. Pratique pour implémenter le SSR et très pratique pour le SEO.
Le composant React exporté par défaut représente la vue. Il s'éxecute à la fin de la méthode loader. Ce composant est exécuté côté serveur puis côté client. C'est dedans qu'on va ajouter nos formulaires, nos states (useState, useEffect, etc ...)
La méthode action (facultative) s'éxecute seulement si une soumission de formulaire POST est effectuée dans la route. Cette méthode contient toute la logique liée à notre mutation (se connecter, s'inscrire, modifier une donnée en DB ...) et va s'exécuter côté serveur.

405 Method Not Allowed signifie qu'on effectue un POST sur notre route, mais qu'on a oublié d'implémenter la logique serveur (on doit déclarer une méthode action)

Ajout de la méthode 'action'

La fonction action est une convention de Remix. Ajoutons cette méthode pour autoriser les requêtes POST dans notre route.

import type { ActionFunctionArgs } from '@remix-run/node';
export const action = async ({ request }: ActionFunctionArgs) => {
    return null;
};

export default function Index() {
    return (
        <form method='POST'>
            <input type='text' name='name' />
            <button type='submit'>S&apos;inscrire</button>
        </form>
    );
}

L'erreur est réparée. On peut passer à la suite.

Validation d'un formulaire côté serveur

Soumettre notre formulaire (en cliquant sur le button) effectue un POST sur notre route, et va déclencher la méthode action. Cette méthode ne fait rien à part renvoyer null.
Nous allons ajouter un peu de logique pour :

extraire les données du formulaire
les valider manuellement
envoyer un retour à l'utilisateur en cas d'erreur

Récupération des données de formulaire côté serveur

Avant de valider les données côté serveur, nous devons les récupérer.
Voici la solution.

import type { ActionFunctionArgs } from '@remix-run/node';
export const action = async ({ request }: ActionFunctionArgs) => {
    const formData = await request.formData();
    const name = formData.get('name');
    return null;
};

export default function Index() {
    return (
        <form method='POST'>
            <input type='text' name='name' />
            <button>S&apos;inscrire</button>
        </form>
    );
}

Explications :

Au moment du POST, notre formulaire va récupérer chaque valeur de ses input possédant la propriété name. Je reformule. Si votre input n'a pas de propriété name, sa valeur ne pourra être récupérée côté serveur. C'est un pré-requis. Cette propriété permet d'identifier l'input côté serveur.

Ensuite, une requête est effectuée à notre action avec les données de notre formulaire. C'est cette requête que nous récupérons comme argument dans notre action. La request possède plusieurs informations, notamment la méthode formData qui va nous permettre de récupérer les données du formulaire. C'est une promesse, nous devons utiliser await.

Cette méthode nous renvoie un objet FormData possédant plusieurs méthodes.

Le FormData n'est pas exclusif à l'environnement serveur. Nous pouvons utiliser cette interface côté client, par exemple en utilisant le props onSubmit dans notre form.

Chaque valeur peut être récupérée en utilisant la méthode .get($key) de notre FormData. $key représente la valeur de la propriété name de l'input. Dans notre cas, nous l'avons appelé name. Je vous présenterai également un moyen de transformer le formData en objet clé-valeur (pour ne plus avoir à utiliser formData.get().

Valider les données de formulaire côté serveur

Pourquoi valider nos données de formulaire ?

Pourquoi valider nos données ? Pour nous assurer que les données reçues sont conformes à ce que nous attendons. Nous allons par exemple valider qu'un numéro de téléphone contient 10 caractères. Sinon, pas la peine de sauvegarder la donnée : On imagine que le numéro est sûrement erroné.

J'ai déjà eu à valider des adresses emails, des numéro SIRET et des numéros de TVA. Ajouter une étape de validation empêche les farceurs de spam notre base de données avec des valeurs inutilisables.

Nous pouvons valider notre donnée de plusieurs manières.

En validant "manuellement" (avec des if)
En utilisant la librairie tiny-invariant
En utilisant Zod

Je n'utilise personnellement jamais la validation manuelle

Validation manuelle de nos données de formulaire

À titre d'exemple, nous allons interdire l'utilisation des prénoms à moins de 3 caractères.

Côté serveur, cela implique deux vérifications :

Vérifier que la valeur est bien un string (et pas un fichier)
Vérifier que le nom fait moins de 3 caractères

Nous devons aussi renvoyer au client un message d'erreur ou de succès.

Côté client, nous faisons quelques modifications :

Nous récupérons le message d'erreur ou de succès avec le hook useActionData
Nous l'affichons conditionnellement à l'utilisateur.

import type { ActionFunctionArgs } from '@remix-run/node';
import { useActionData } from '@remix-run/react';
export const action = async ({ request }: ActionFunctionArgs) => {
    const formData = await request.formData();
    const name = formData.get('name');

    if (typeof name !== 'string') {
        return {
            message: 'Le nom est requis',
        };
    }

    if (name.length < 3) {
        return {
            message: 'Le nom doit contenir au moins 3 caractères',
        };
    }
    return { message: 'Inscription réussie' };
};

export default function Index() {
    const actionData = useActionData<typeof action>();
    return (
        <form method='POST'>
            <input type='text' name='name' />
            {actionData?.message ? <p>{actionData.message}</p> : null}
            <button>S&apos;inscrire</button>
        </form>
    );
}

Pour un cas d'utilisation très simple comme celui-ci, on peut s'arrêter là. Pas besoin d'installer deux librairies supplémentaires. Cependant, cet exemple ne reflète pas les applications que je pousse en production. Il y a souvent plus de trois champs aux formulaires que je développe. De plus, j'utilise déjà la librairie zod pour valider les données côté serveur (récupérées depuis une API NestJS)

Validation de nos données de formulaire avec Zod

Pour pouvoir utiliser Zod, (c'est une librairie Javascript de validation de données), nous avons besoin de l'installer dans notre dossier projet.

npm install zod

Ensuite, nous définissons un schéma représentant notre modèle de données. Reprenons l'exemple de notre nom à 3 caractères qui est de type string. Cela implique une refactorisation du code.

Nous devons définir le schéma zod en ajoutant les instructions .string() et .min(3) (les messages d'erreurs sont facultatifs).

const nameSchema = z.string({ required_error: 'Le nom est requis' }).min(3, {
    message: 'Le nom doit contenir au moins 3 caractères',
});

Ensuite, nous allons utiliser la méthode .parse($data) pour déclencher la validation de notre donnée $data (ici, ce sera notre name).

const parsedName = nameSchema.parse(name);

Voici l'implémentation complète.

import type { ActionFunctionArgs } from '@remix-run/node';
import { useActionData } from '@remix-run/react';
import { z } from 'zod';

const nameSchema = z.string({ required_error: 'Le nom est requis' }).min(3, {
    message: 'Le nom doit contenir au moins 3 caractères',
});
export const action = async ({ request }: ActionFunctionArgs) => {
    const formData = await request.formData();
    const name = formData.get('name');
    const parsedName = nameSchema.parse(name);
    return { message: 'Inscription réussie' };
};

export default function Index() {
    const actionData = useActionData<typeof action>();
    return (
        <form method='POST'>
            <input type='text' name='name' />
            {actionData?.message ? <p>{actionData.message}</p> : null}
            <button>S&apos;inscrire</button>
        </form>
    );
}

Cette implémentation possède un avantage et un inconvénient.

L'avantage c'est la validation Zod qui permet de réutiliser cette logique (en exportant le schéma). C'est simple à maintenir et c'est lisible.
Le désavantage, c'est qu'en cas d'erreur (si le schéma n'est pas respecté), le message d'erreur de Zod ne sera pas affiché côté client.

ZodError: [
  {
    "code": "too_small",
    "minimum": 3,
    "type": "string",
    "inclusive": true,
    "exact": false,
    "message": "Le nom doit contenir au moins 3 caractères",
    "path": []
  }
]
    at Object.get error [as error] (file:///Users/dev/dev/remix-forms/node_modules/zod/lib/index.mjs:538:31)
    at ZodString.parse (file:///Users/dev/dev/remix-forms/node_modules/zod/lib/index.mjs:638:22)
    at action2 (file:///Users/dev/dev/remix-forms/app/routes/_index.tsx:11:32)
    ```



Nous avons deux solutions, chacune avec des avantages et des inconvénients.

##### Implémenter nous-même la gestion des erreurs Zod en utilisant 'safeParse'

Cette solution possède un avantage : ne pas installer une librairie supplémentaire.
L'inconvénient, c'est que plus le schéma devient complexe, plus la gestion des erreurs devient complexe

##### Utiliser la librairie Conform pour gérer les erreurs
Cette [librairie](https://conform.guide/) a été conçue spécifiquement pour ce cas d'utilisation (validation de formulaires avec Remix et Zod)

L'avantage principal, c'est que même avec un schéma complexe, le développeur n'aura pas plus de mal à implémenter le formulaire.
Le désavantage, c'est qu'il faut installer une nouvelle librairie. Ça peut être un problème si vous ne voulez pas davantage ralentir votre webapp avec du JS.

Cet article est biaisé, car il parle de l'intégration de Conform dans votre application Remix.

#### Validation des données de formulaire avec Conform

Nous avons besoin d'installer deux librairies pour utiliser Conform.

- `@conform-to/react` pour utiliser son puissant hook `useForm`, valider les données côté client et afficher les erreurs
- `@conform-to/zod` pour valider les données côté serveur et côté client avec Zod. Sans déclencher d'erreur en cas de non-validation.



```bash
npm install @conform-to/react @conform-to/zod

Nous allons implémenter Conform en trois étapes. Modifier le schéma Zod (et l'adapter à Conform), ajouter la logique côté client, puis ajouter la logique côté serveur.

Adapter le schéma Zod à Conform

const nameSchema = z.string({ required_error: 'Le nom est requis' }).min(3, {
    message: 'Le nom doit contenir au moins 3 caractères',
});

const Schema = z.object({
    name: nameSchema,
});

Bien que ce formulaire ne possède qu'une propriété pour l'instant, Conform s'attend à recevoir un FormData en paramètres. Il le transforme ensuite en objet. Nous avons déclaré un nouveau Schema qui est un z.object, contenant une propriété name (qui utilise le schéma que nous avons défini toute à l'heure).

Ajouter 'useForm' côté client

Conform utilise le schéma Zod pour déterminer les champs de notre formulaire. Notre Schema possède un champ (name). Nous utilisons le hook useForm pour récupérer les props de notre formulaire et de chacun de nos input (les fields).

import { getFormProps, getInputProps, useForm } from '@conform-to/react';
import { getZodConstraint, parseWithZod } from '@conform-to/zod';
import { z } from 'zod';

const nameSchema = z.string({ required_error: 'Le nom est requis' }).min(3, {
    message: 'Le nom doit contenir au moins 3 caractères',
});

const Schema = z.object({
    name: nameSchema,
});

export default function Index() {
    const [form, fields] = useForm({
        constraint: getZodConstraint(Schema),
        onValidate({ formData }) {
            return parseWithZod(formData, {
                schema: Schema,
            });
        },
        lastResult: undefined,
    });
    return (
        <form {...getFormProps(form)} method='POST'>
            <input {...getInputProps(fields.name, { type: 'text' })} />
            <div>{fields.name.errors}</div>
            <button>S&apos;inscrire</button>
        </form>
    );
}

On peut constater qu'on ne définit aucun props sur nos input. C'est Conform qui gère leur valeur, leur ID, le focus en cas d'erreur et plein d'autres fonctionnalités lié au progressive enhancement pour offrir à nos utilisateurs une expérience optimale.

Constatez aussi la méthode parseWithZod, utilisée pour valider les données du formData côté client, dans la méthode onValidate. C'est exactement ce que nous avons fait tout à l'heure côté serveur ! Le FormData vient du client, et n'est envoyé au serveur qu'après la soumission (et la première validation par Conform et Zod)

Validation des données côté serveur avec Conform et 'parseWithZod'

Il nous manque la validation la plus importante. Celle qui est effectuée côté serveur. C'est dans notre action qu'on va vérifier les informations fournies par l'utilisateur. (Est-ce que l'utilisateur existe déjà ? A-t-il validé son mot de passe ? Ces exemples sont utilisés dans toutes les applications, même si notre implémentation ne le reflète pas)

import { ActionFunctionArgs, json } from '@remix-run/node';
import { z } from 'zod';

const nameSchema = z.string({ required_error: 'Le nom est requis' }).min(3, {
    message: 'Le nom doit contenir au moins 3 caractères',
});

const Schema = z.object({
    name: nameSchema,
});

export const action = async ({ request }: ActionFunctionArgs) => {
    const formData = await request.formData();
    const submission = await parseWithZod(formData, {
        schema: Schema,
    });
    if (submission.status !== 'success') {
        return json({ result: submission.reply() });
    }

    return json({
        result: submission.reply({
            resetForm: true,
        }),
    });
};

Nous devons toujours récupérer les valeurs du formulaire avec await request.formData(), sauf que cette fois on laisse Conform se charger de tout, grâce à la méthode parseWithZod. Cette méthode prend le formData et notre schéma Zod en deuxième argument.

Il nous renvoie ensuite un objet submission, qui possède l'un des deux status : error et success.

Si le statut error est renvoyé, alors nous renvoyons une réponse Conform au client. Nous devons ensuite la passer comme argument dans le hook useForm (clé lastResult) pour qu'il puisse faire le lien entre la soumission qui a échouée côté serveur, et les inputs côté client.
Si le statut success est renvoyé, cela signifie que les données sont conformes au schéma. Il n'y a rien de plus à faire. On a implémenté la validation côté serveur.

Voici le composant intégral (avec le lastResult)

 import { getFormProps, getInputProps, useForm } from '@conform-to/react';
import { getZodConstraint, parseWithZod } from '@conform-to/zod';
import { ActionFunctionArgs, json } from '@remix-run/node';
import { useActionData } from '@remix-run/react';
import { z } from 'zod';

const nameSchema = z.string({ required_error: 'Le nom est requis' }).min(3, {
    message: 'Le nom doit contenir au moins 3 caractères',
});

const Schema = z.object({
    name: nameSchema,
});

export const action = async ({ request }: ActionFunctionArgs) => {
    const formData = await request.formData();
    const submission = await parseWithZod(formData, {
        schema: Schema,
    });
    if (submission.status !== 'success') {
        return json({ result: submission.reply() });
    }

    return json({
        result: submission.reply({
            resetForm: true,
        }),
    });
};

export default function Index() {
    const actionData = useActionData<typeof action>();
    const [form, fields] = useForm({
        constraint: getZodConstraint(Schema),
        onValidate({ formData }) {
            return parseWithZod(formData, {
                schema: Schema,
            });
        },
        lastResult: actionData?.result,
    });
    return (
        <form {...getFormProps(form)} method='POST'>
            <input {...getInputProps(fields.name, { type: 'text' })} />
            <div>{fields.name.errors}</div>
            <button>S&apos;inscrire</button>
        </form>
    );
}

Conclusion

En explorant l'implémentation d'un formulaire étape par étape avec Remix, nous avons découvert l'importance cruciale de l'expérience utilisateur (UX) dans la gestion des erreurs. Commencer par les fondamentaux nous a permis de comprendre comment récupérer et valider les données de formulaire côté serveur.

L'utilisation de Zod nous a permis de consolider la validation des données, en ajoutant des messages d'erreurs clairs, tout en restant plus simple à maintenir qu'une gestion d'erreur "manuelle".

Utiliser Conform nous a permi d'optimiser l'expérience utilisateur grâce à une validation efficace et des retours visuels, pour prévenir les utilisateurs de leurs erreurs éventuelles avec des messages d'erreurs de qualité.

Je vous encourage à tester Remix avec ces outils ! Depuis que je les ai découvert, je ne m'en sépare plus.

Votre feedback est précieux — n'hésitez pas à partager vos expériences, questions ou suggestions sur Twitter ou sur LinkedIn si ça vous a été utile. Ensemble, améliorons l'UX de nos formulaires et offrons une expérience agréable à nos utilisateurs.

6 Routes à connaître si tu utilises Remix (guide complet)

Virgile RIETSCH — Tue, 13 Feb 2024 07:21:35 +0000

Envisages-tu de tester ou même d'utiliser le framework Remix pour ton prochain projet ?

Pour cela, il va falloir te familiariser avec son puissant routing. Cet article te liste les 6 types de routes que tu vas utiliser au quotidien avec Remix. Si tu préfères lire la doc, Remix explique tout en détail sur le site.

Le routing, c'est quoi ?

Commençons par définir ce qu'est le routing

C'est le chemin (sous forme d'URL) qui permet d'accéder à ton site internet

Exemples :

leboncoin.fr te permet d'accéder à la page d'accueil du bon coin, sa route "index".
leboncoin.fr/annonces/offres te permet d'accéder à une deuxième page du bon coin. La page est différente de la première, le chemin d'accès dans l'URL est différent. C'est une deuxième route.

Tous les sites possèdent minimum une route (qu'on va appeler route index, ou route par défaut).

Ce concept n'est pas récent. À mes débuts dans le développement, j'intégrais mes premières pages en HTML et PHP. La convention était de nommer nos fichiers index.html et index.php. Ces fichiers étaient ensuite accessibles au nom de domaine local. Par exemple, localhost:8000. Sans le savoir, j'avais déjà créé ma première route index.

Avec l'arrivée de React et de ses framework, le routing se fait généralement sans configuration de notre part. (sauf si tu utilises React-Router, mais si c'est le cas, tu es au bon endroit !)

Explication vidéo

Nous avons fait un guide vidéo pour t'expliquer le routing de Remix avec plus d'exemples.

Créer sa première route (type 1)

Lorsques tu génères un nouveau projet Remix avec l'un de ses nombreux template, une route par défaut aura déjà été créée. Elle se situe dans ton dossier app/routes et se nomme __index.tsx.

export default function Index() {
    return (
        <h1>Hello world !</h1>
    );
}

Voici les 2 règles à respecter pour créer une route avec la configuration par défaut de Remix :

Créer un fichier au format .jsx ou .tsx dans le dossier app/routes.
Le nommer (son nom va définir le chemin pour y accéder dans l'URL.

Dans l'exemple ci-dessous, nous avons ajouté un composant React à l'intérieur de notre fichier. Cette vue sera accessible à la page d'accueil de notre site (par défaut localhost:3000)

Mais il n'est pas obligatoire d'exporter des composants React depuis nos routes.

Cela dépend de ton besoin. Si tu veux juste créer un endpoint API (une route qui renvoie du JSON, par exemple), tu n'as pas besoin de déclarer un composant React.

export const loader = () => {
   return { name: 'Virgile' }
}

Voici un exemple d'une route Remix, accessible à l'URL localhost:3000/api. Elle renvoie un objet au format JSON.

{ name: "Virgile" }

Création d'une route dynamique (type 2)

Pour créer une route dynamique, nous devons utiliser un nommage de fichier précis. Il nous suffit d'ajouter le préfixe $ à notre nom de fichier.

Par exemple, si je souhaite afficher le détail de l'utilisateur Virgile* à l'adresse http://localhost:3000/users/virgile, je vais implémenter cette logique en deux étapes :

Nommer un fichier dans le dossier app/routes, nommé users.$username.tsx
Exporter par défaut un composant React pour afficher une vue, avec les informations de cet utilisateur

Regardons avec un exemple.

import { useParams } from '@remix-run/react';
export default function Username() {
    const username = useParams().username;
    return (
        <h1>Salut {username} !</h1>
    );
}

Ici, nous donnons une instruction à Remix. Nous lui demandons de créer une route au chemin users/virgile. Le point (.) dans le nommage du fichier nous permet d'ajouter un slash dans l'URL. Ensuite, le $ nous permet de nommer la clé du paramètre dans l'URL.

Nous récupérons ensuite ce paramètre dynamique, nommé username dans notre composant React, côté client à l'aide du hook useParams() que nous importons depuis Remix.

Ce fichier nous permet donc de créer une route qui va afficher une vue côté client, avec une valeur dynamique en fonction de la valeur que nous entrons dans l'URL.

La valeur de notre variable username est déterminée par le paramètre d'URL (soit virgile, dans cet exemple)

Création d'une route imbriquée (type 3)

La route imbriquée est similaire à la route dynamique. Nous nommons le fichier de la même manière qu'une route dynamique. La seule différence, c'est le contenu de la route parent (dans notre exemple, la route users.tsx) est visible sur la page. C'est très pratique pour afficher par exemple système d'onglets dans notre application.

Nous pourrions très bien reproduire cet exemple sous forme de route imbriquée. La route parent afficherait les onglets, et le contenu de l'onglet (Subtopic 1) serait affiché dans la route enfant.

Faisons d'abord une petite refactorisation.

import { Link } from '@remix-run/react';

export default function Users() {
    return (
        <div>
            <h1>Liste des utilisateurs</h1>
            <ul>
                {['Virgile', 'Cédric'].map((username) => (
                    <Link to={`/users/${username}`} key={username}>
                        {username}
                    </Link>
                ))}
            </ul>
        </div>
    );
}

Nous affichons maintenant une liste de deux utilisateurs sur la route localhost:3000/users, Virgile et Cédric.
Nous avons également des liens pour accéder à leur information.

Spoiler, mais ça ne va pas avoir l'effet désiré. On n'est cependant pas loin du but.
En théorie, il suffirait de changer l'URL à localhost:3000/cedric pour afficher la vue pour cet utilisateur (c'est la route dynamique que nous avons créée plus haut).

Malheureusement, après avoir cliqué sur le lien, on se rend compte que la page n'a pas changé 🤔 ??

Et bien, si. Nous avons réussi à donne l'instruction à Remix de créer une route imbriquée. Sauf qu'on a oublié un composant magique nous permettant de placer la position de l'enfant dans le DOM.

En fait, la page ci-dessus affiche toujours le contenu du parent (les liens de nos utilisateurs), mais elle n'affiche pas la route enfant car on ne lui a pas donné l'instruction. (il n'y a donc aucun bug, rassurez-vous)

Que dois-je faire pour faire apparaître ma route enfant ?

Le composant <Outlet/> est la pièce manquante pour bénéficier des routes imbriquées avec Remix. En effet, si nous accédons à la route parent (localhost:3000/users), Remix affiche la route users.tsx. Mais si on accède à la route localhost:3000/users/cedric, Remix va regarder le nom de notre fichier users.$userId.tsx.

Et il va vérifier trois éléments :

Est-ce qu'il y a un paramètre d'URL dynamique (symbolisé par le $)
Est-ce qu'il existe une route parent (dans notre cas, users.tsx
Est-ce que la route parent possède un composant <Outlet/>

Rajoutons maintenant le composant Outlet et regardons ce qui se passe.

import { Link, Outlet } from '@remix-run/react';

export default function Users() {
    return (
        <div>
            <h1>Liste des utilisateurs</h1>
            <ul>
                {['Virgile', 'Cédric'].map((username) => (
                    <Link to={`/users/${username}`} key={username}>
                        {username}
                    </Link>
                ))}
            </ul>
            <Outlet />
        </div>
    );
}

En résumé, ajouter une route imbriquée est relativement simple. Il suffit de rajouter le composant <Outlet/> dans la route parent. Et Remix se charge du reste.

Création d'une route layout (type 4)

Reprenons l'exemple de nos onglets pour mieux comprendre l'intérêt d'une route layout.
On va commencer par la définir, en la comparant à une route imbriquée.

Une route layout, c'est une route imbriquée, mais le chemin n'est pas visible dans l'URL.

Par exemple, si vous souhaitez afficher un composant spécial sur certaines pages, mais pas sur d'autres (ou bien un modal qui apparaît après 5 secondes, c'est vous qui voyez), c'est totalement possible grâce aux routes Layout.

Pour créer une route layout, il suffit de rajouter le préfixe _ (underscore) à la route parent. Son nom va disparaître de l'URL.
Essayons tout de suite avec notre route users.tsx.

(Le contenu du fichier ne change pas, seulement son nom)

import { Link, Outlet } from '@remix-run/react';

export default function Users() {
    return (
        <div>
            <h1>Liste des utilisateurs</h1>
            <ul>
                {['Virgile', 'Cédric'].map((username) => (
                    <Link to={`/${username}`} key={username}>
                        {username}
                    </Link>
                ))}
            </ul>
            <Outlet />
        </div>
    );
}

Il faut aussi modifier le fichier users.$username.tsx pour qu'il soit considéré comme "faisant partie du layout".

import { useParams } from '@remix-run/react';

export default function Username() {
    const username = useParams().username;
    return <h1>Salut {username} !</h1>;
}

Maintenant, notre liste d'utilisateurs ne sera plus visible au chemin localhost:3000/users. Elle ne sera plus visible du coup, pas même à l'URL localhost:3000 (c'est la route _index.tsx qui s'affiche à la place).

Le détail de notre utilisateur sera cependant accessible à la route enfant localhost:3000/cedric, ainsi que le contneu de notre layout (la liste de nos deux utilisateurs)

Créer une route ressource (JSON, PDF, CSV ...) (type 5)

Vous vous souvenez de la route basique qu'on a créé en tout début de l'article ? Une route ressource est exactement pareil.

Il suffit de créer un fichier dans le dossier app/routes, mais au lieu d'exporter un composant React par défaut (notre vue), nous exportons une méthode nommée loader (pas besoin de l'exporter par défaut)

Essayons avec un exemple. Je souhaite afficher une image aléatoire à l'URL localhost:3000/image. Je vais donc récupérer mon image depuis le site picsum.photos

Il me suffit donc de créer un fichier nommé image.tsx (dans le dossier app/routes), puis d'exporter une fonction nommée loader
Essayons voir.

export const loader = async () => {
    const response = await fetch('https://picsum.photos/200/300');
    const blob = await response.blob();
    return new Response(blob, {
        headers: {
            'Content-Type': 'image/jpeg',
        },
    });
};

Je n'ai jamais créé une route API aussi facilement.

Créer une route 404 (type 6)

Nous allons maintenant créer notre dernier type de route, la fameuse page Erreur 404.
Si vous lisez l'article depuis le début, vous comprendrez vite comment l'implémenter.
Indice : C'est comme une route dynamique, mais le paramètre d'URL n'est pas nommé.

Il faut nommer le fichier $.tsx

Pour afficher une vue à n'importe quelle page que Remix n'identifie pas comme étant un chemin valide, il faut également exporter un composant React par défaut. Passons à l'implémentation.

import { useLocation } from '@remix-run/react';

export default function FourOhFour() {
    const location = useLocation();
    return (
        <h1 style={{ fontSize: 18 }}>
            Oops, on a pas trouvé la route{' '}
            <span style={{ color: 'GrayText' }}>{location.pathname}</span> !
        </h1>
    );
}

Essayons un chemin pour voir. Au hasard, localhost:3000/youtube/abonnez-vous.

Petites précisions :

Remix priorise les routes nommées. Si vous tapez localhost:3000/image dans l'URL, Remix va d'abord regarder les routes nommées, pas dynamiques (un match exact) avec le nom. C'est le cas pour nous avec le fichier image.tsx
Ensuite s'il ne trouve pas, il va chercher une route dynamique (avec le préfixe $). C'est le cas avec le fichier _users.$username.tsx, qui va matcher n'importe qu'elle URL à la place de l'étoile localhost:3000/*, à l'exception des routes nommées (exact match), et des routes imbriquées (plusieurs / (slash) dans l'URL)
Nous essayons d'accéder à la route localhost:3000/youtube/abonnez-vous, qui n'est donc pas un paramètre d'URL car il y a un /. On renvoie donc sur une page 404.

Conclusion

Nous venons de voir tous les types de page nécessaires pour vous permettre de créer des belles applications web sur mesure. Si vous voulez aller plus loin et configurer vous-même vos règles de routing (ou changer les préfixes, tels que ., $ et _, c'est possible. La librairie remix-flat-routes vous le permet, et je l'utilise dans tous mes projets !