Interface utilisateur · Référence
Composants React et CSS
Installez le fournisseur, les formulaires, contrôles de compte, gardes d'accès et la source Tailwind du paquet.
Le paquet fournit des composants Better Auth prêts à l'emploi tout en laissant la mise en page et la navigation sous le contrôle de l'application.
Configuration Tailwind CSS
Importez la source du paquet dans le CSS global afin que Tailwind détecte les classes compilées :
@import "tailwindcss";
@import "@krak-stack/auth/tailwind.css";Les composants utilisent les variables shadcn comme --background, --foreground, --primary, --border et --radius. Définissez-les dans :root et .dark, normalement via votre thème shadcn existant.
Fournisseur
import { KrakstackAuthProvider } from "@krak-stack/auth/components";
import { KrakstackProvider } from "@krak-stack/registry/krakstack-provider";
import { getLocale, locales } from "@/paraglide/runtime";
<KrakstackProvider locale={getLocale()} locales={locales}>
<KrakstackAuthProvider
projectId={import.meta.env.VITE_KRAKSTACK_AUTH_PROJECT_ID}
>
{children}
</KrakstackAuthProvider>
</KrakstackProvider>;Fournissez baseUrl si le point de même origine par défaut ne convient pas. Le fournisseur et les composants utilisent en interne le client Effect HttpApi fourni; ils n'acceptent pas de client Better Auth.
Synchronisation de la langue
KrakstackAuthProvider lit la langue de l'interface depuis le KrakstackProvider qui l'englobe. Il n'accepte pas de prop locale. La langue du contexte fait autorité : le fournisseur l'enregistre dans le champ locale de l'utilisateur connecté pour les courriels et les autres communications asynchrones. Il ne restaure pas la langue de l'interface depuis la préférence du compte lors de la connexion.
Utilisez le sélecteur de langue directement depuis le registre. Il change uniquement la langue de l'interface; l'enregistrement de la préférence appartient au fournisseur auth, pas à un composant personnalisé autour du sélecteur :
import { LocaleSwitcher } from "@krak-stack/registry/locale-switcher";
import { setLocale } from "@/paraglide/runtime";
<LocaleSwitcher
onLocaleChange={(locale) => setLocale(locale === "fr" ? "fr" : "en")}
/>;Le flux est LocaleSwitcher → Paraglide → KrakstackProvider → KrakstackAuthProvider → user.locale. Avec le rechargement par défaut de Paraglide, la nouvelle page fournit la langue actualisée du contexte et la synchronisation démarre après le chargement de sa session. Si votre application change de langue sans rechargement, elle doit effectuer un nouveau rendu de KrakstackProvider avec la nouvelle valeur de locale.
| Situation | Comportement |
|---|---|
| La session se charge ou s'actualise | Attendre; ne pas modifier l'utilisateur. |
| Le visiteur n'est pas connecté | Conserver la langue du navigateur; ne modifier aucun utilisateur. |
| La session utilise l'identité d'un autre utilisateur | Ne pas modifier la préférence enregistrée de cet utilisateur. |
| La langue enregistrée correspond au contexte | Ne pas envoyer de requête de mise à jour. |
| La langue enregistrée de l'utilisateur connecté diffère ou est absente | Enregistrer la langue du contexte avec une mise à jour optimiste, puis revalider les requêtes de session. |
| L'enregistrement échoue | Annuler l'état optimiste, journaliser l'échec et appeler onLocaleSyncError si fourni. Ne pas réessayer en boucle pour la même paire utilisateur/langue. |
Utilisez le callback facultatif onLocaleSyncError de KrakstackAuthProvider pour afficher un message d'erreur localisé propre à l'application. Il reçoit la cause de l'échec; modifier sa référence ne relance pas un enregistrement échoué.
Pages publiques et liens localisés
Placez KrakstackProvider autour de tout le site et KrakstackAuthProvider uniquement autour des routes qui doivent synchroniser la langue du compte. Un sélecteur sur une page publique hors du fournisseur auth change uniquement la langue du navigateur, même si le visiteur possède une session. L'accès ultérieur à une route englobée par le fournisseur synchronise cette langue avec le compte.
La synchronisation suit le contexte, pas seulement les clics explicites sur le sélecteur. Ouvrir une URL localisée dans le fournisseur auth peut donc modifier la préférence enregistrée. Ouvrir une page publique localisée hors de ce fournisseur ne la modifie pas. Si le fournisseur auth englobe tout le site, les pages publiques synchroniseront aussi la langue.
Inscription et communications aux destinataires
Les nouveaux comptes initialisent leur langue depuis le contexte validé du parcours d'inscription, avec l'anglais comme repli. Les comptes existants sans préférence précédemment enregistrée utilisent l'anglais après la migration. L'anglais (en) et le français (fr) sont actuellement pris en charge; la colonne de langue en base n'impose aucune contrainte de langue, tandis que les écritures API valident les valeurs prises en charge.
Les fonctions d'envoi de courriels de Krakstack Auth privilégient la langue enregistrée du destinataire. En l'absence de préférence valide, elles utilisent la langue de la requête si elle est disponible, sinon l'anglais. Pour un destinataire connu, cela fonctionne sans requête navigateur. Pour les notifications de fond propres à votre application, utilisez aussi la langue enregistrée du destinataire, pas celle de l'administrateur ou du processus à l'origine de l'envoi. Les canaux de livraison n'ont pas besoin d'une préférence de langue distincte.
Contrôles de compte
import {
OrganizationSwitcher,
UserButton,
} from "@krak-stack/auth/components";
<OrganizationSwitcher side="bottom" />
<UserButton signOutRedirect="/" side="bottom" />UserButton permet aussi de gérer des courriels publics, numéros de téléphone, sites Web et profils sociaux avec des libellés localisés. Ces valeurs sont distinctes du courriel utilisé pour la connexion et sont accessibles aux clients de l'API serveur de confiance.
Formulaires
Le paquet exporte Signin, VerifyEmail, ForgotPassword, ResetPassword et TwoFactor. ResetPassword affiche la demande par courriel sans jeton et le nouveau mot de passe avec un jeton; ForgotPassword reste disponible si seule l'étape du courriel est nécessaire. Affichez les formulaires dans vos propres routes afin de garder le contrôle des URL, métadonnées et limites d'erreur.
Garde d'autorisation
MemberRequired protège la présentation selon l'adhésion à une organisation, mais chaque endpoint backend doit aussi vérifier indépendamment la session, l'organisation et le rôle. Une garde frontend n'est jamais une frontière d'autorisation.
Hooks, atomes et contrat
Importez useKrakstackAuth, useKrakstackAuthProjectConfig et usePermissions depuis @krak-stack/auth/components dans le fournisseur. Pour accéder directement à l'état Effect, utilisez authSessionAtom, authOrganizationsAtom et activeAuthOrganizationAtom depuis le même sous-chemin avec @effect/atom-react. Utilisez le contrat HttpApi @krak-stack/auth/auth lorsqu'un client Effect personnalisé est nécessaire.