From b2cf4883c2d84b46e387a834983131b38be47e0a Mon Sep 17 00:00:00 2001 From: Joachim Justh Date: Wed, 4 Jan 2023 23:00:34 -0500 Subject: [PATCH] docs: update french docs with #934 --- www/src/pages/fr/folder-structure.mdx | 56 +++++++++--------------- www/src/pages/fr/t3-collection.md | 3 ++ www/src/pages/fr/usage/first-steps.md | 2 +- www/src/pages/fr/usage/next-auth.md | 10 ++--- www/src/pages/fr/usage/prisma.md | 4 +- www/src/pages/fr/usage/trpc.md | 61 +++++++++++++++------------ 6 files changed, 64 insertions(+), 72 deletions(-) diff --git a/www/src/pages/fr/folder-structure.mdx b/www/src/pages/fr/folder-structure.mdx index b899bc0cda..c84bfa395c 100644 --- a/www/src/pages/fr/folder-structure.mdx +++ b/www/src/pages/fr/folder-structure.mdx @@ -63,7 +63,7 @@ Le fichier `[...nextauth].ts` est la route d'authentification NextAuth.js. Il es Le fichier `[trpc].ts` est le point d'entrée de l'API tRPC. Il est utilisé pour gérer les requêtes tRPC. Voir [utilisation de tRPC](usage/trpc#-pagesapitrpctrpcts) pour plus d'informations sur ce fichier, et la [documentation Next.js sur les routes dynamiques](https://nextjs.org/docs/routing/dynamic-routes) pour plus d'informations sur les routes fourre-tout / slug. -
+
### `src/server` @@ -72,72 +72,56 @@ Le dossier `server` est utilisé pour séparer clairement le code côté serveur
-### `src/server/common` +### `src/server/auth.ts` -Le dossier "common" contient du code côté serveur couramment réutilisé. - -
-
- -#### `src/server/common/get-server-auth-session.ts` - -Le fichier `get-server-auth-session.ts` est utilisé pour obtenir la session NextAuth.js côté serveur. Voir [utilisation de NextAuth.js](usage/next-auth#utilisation-avec-trpc) pour plus d'informations. +Contient des utilitaires d'authentification tels que la récupération de la session de l'utilisateur côté serveur. Voir [utilisation de NextAuth.js](usage/next-auth#utilisation-avec-trpc) pour plus d'informations.
-#### `src/server/db/client.ts` +#### `src/server/db.ts` -Le fichier `client.ts` est utilisé pour instancier le client Prisma au niveau global. Voir [Utilisation de Prisma](usage/prisma#prisma-client) pour plus d'informations. +Le fichier `db.ts` est utilisé pour instancier le client Prisma au niveau global. Voir [Utilisation de Prisma](usage/prisma#prisma-client) et [meilleures pratiques pour utiliser Prisma avec Next.js](https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices) pour plus d'informations.
-### `src/server/trpc` +### `src/server/api` -Le dossier `trpc` contient le code côté serveur de tRPC. +Le dossier `api` contient le code côté serveur de tRPC.
-#### `src/server/trpc/context.ts` +#### `src/server/api/routers` -Le fichier `context.ts` est utilisé pour créer le contexte utilisé dans les requêtes tRPC. Voir [utilisation de tRPC](usage/trpc#-servertrpccontextts) pour plus d'informations. +Le dossier `routers` contient tous vos sous-routeurs tRPC.
-#### `src/server/trpc/trpc.ts` +#### `src/server/api/routers/example.ts` -Le fichier `trpc.ts` est utilisé pour exporter les assistants de procédure. Voir [utilisation de tRPC](usage/trpc#-servertrpctrpcts) pour plus d'informations. +Le fichier `example.ts` est un exemple de routeur tRPC utilisant le helper `publicProcedure` pour montrer comment créer une route tRPC publique. -
-
- -### `src/server/trpc/router` - -Le dossier `router` contient les routeurs tRPC. +En fonction des packages choisis, ce routeur contient plus ou moins de routes pour démontrer au mieux l'utilisation à vos besoins.
-#### `src/server/trpc/router/_app.ts` - -Le fichier `_app.ts` est utilisé pour fusionner les routeurs tRPC et les exporter en tant que routeur unique, ainsi que les définitions de type. Voir [utilisation de tRPC](usage/trpc#-servertrpcrouterts) pour plus d'informations. - -
-
+#### `src/server/api/trpc.ts` -#### `src/server/trpc/router/auth.ts` +Le fichier `trpc.ts` est le fichier de configuration principal de votre back-end tRPC. Ici, vous trouverez: -Le fichier `auth.ts` est un exemple de routeur tRPC utilisant l'assistant `protectedProcedure` pour montrer comment protéger une route tRPC avec NextAuth.js. +1. La définissons du contexte utilisé dans les requêtes tRPC. Voir [utilisation de tRPC](usage/trpc#-servertrpccontextts) pour plus d'informations. +2. Le helper de procédure d'exportation. Voir [utilisation de tRPC](usage/trpc#-servertrpctrpcts) pour plus d'informations.
-#### `src/server/trpc/router/example.ts` +#### `src/server/api/root.ts` -Le fichier `example.ts` est un exemple de routeur tRPC utilisant l'assistant `publicProcedure` pour montrer comment créer une route tRPC publique. +Le fichier `root.ts` est utilisé pour fusionner les routeurs tRPC et les exporter en tant que routeur unique, ainsi que la définition du type de routeur. Voir [utilisation du tRPC](usage/trpc#-servertrpcrourts) pour plus d'informations.
@@ -170,9 +154,9 @@ Le dossier `utils` est utilisé pour stocker les fonctions utilitaires courammen
-#### `src/utils/trpc.ts` +#### `src/utils/api.ts` -Le fichier `trpc.ts` est le point d'entrée frontal de tRPC. Voir [utilisation de tRPC](usage/trpc#-utilstrpcts) pour plus d'informations. +Le fichier `api.ts` est le point d'entrée frontal de tRPC. Voir [utilisation de tRPC](usage/trpc#-utilstrpcts) pour plus d'informations.
diff --git a/www/src/pages/fr/t3-collection.md b/www/src/pages/fr/t3-collection.md index f7929cf7b2..46639b8640 100644 --- a/www/src/pages/fr/t3-collection.md +++ b/www/src/pages/fr/t3-collection.md @@ -25,6 +25,9 @@ Vous avez réalisé un projet à l'aide de la stack T3 et souhaitez le partager | The Doom | [moltivie/slug](https://github.com/Moltivie/the-t3-stack) | [the-t3-stack.vercel.app](https://the-t3-stack.vercel.app) | | Railtrack | [noahflk/railtrack](https://github.com/noahflk/railtrack) | [railtrack.flk.li](https://railtrack.flk.li) | | Boutique KARA - Site e-commerce | [mehrabmp/kara-shop](https://github.com/mehrabmp/kara-shop) | [karashop.vercel.app](https://karashop.vercel.app/) | +| Tauri T3 App - Application Tauri qui utilise la T3 Stack | [tauri-t3-app](https://github.com/AyanavaKarmakar/tauri-t3-app) | [tauri-t3-app.docs](https://github.com/AyanavaKarmakar/tauri-t3-app#readme) | +| Azon - Site e-commerce | [andrewsolonets/Azon-Shop](https://github.com/andrewsolonets/Azon-Shop) | [azon-shop.vercel.app](https://azon-shop.vercel.app/) | +| Analyzemyrepo.com - Informations utiles pour **tout** GitHub repo | [CrowdDotDev/analyzemyrepo](https://github.com/CrowdDotDev/analyzemyrepo) | [analyzemyrepo.com](https://analyzemyrepo.com) | ## Entreprises utilisant la stack T3 diff --git a/www/src/pages/fr/usage/first-steps.md b/www/src/pages/fr/usage/first-steps.md index d73b473e6d..d2bf08929b 100644 --- a/www/src/pages/fr/usage/first-steps.md +++ b/www/src/pages/fr/usage/first-steps.md @@ -32,6 +32,6 @@ Vous devriez maintenant pouvoir vous connecter. ## Prochaines étapes -- Si votre application inclut tRPC, consultez `src/pages/index.tsx` et `src/server/trpc/router/example.ts` pour voir comment fonctionnent les requêtes tRPC. +- Si votre application inclut tRPC, consultez `src/pages/index.tsx` et `src/server/api/routers/example.ts` pour voir comment fonctionnent les requêtes tRPC. - Consultez la documentation `create-t3-app`, ainsi que la documentation des packages inclus dans votre application. - Rejoignez notre [Discord](https://t3.gg/discord) et donnez-nous une étoile sur [GitHub](https://github.com/t3-oss/create-t3-app) ! :) diff --git a/www/src/pages/fr/usage/next-auth.md b/www/src/pages/fr/usage/next-auth.md index 2cf2476695..8b5588afa2 100644 --- a/www/src/pages/fr/usage/next-auth.md +++ b/www/src/pages/fr/usage/next-auth.md @@ -73,7 +73,7 @@ Cela se fait en deux étapes : 1. Récupérez la session à partir des en-têtes de requête à l'aide de la fonction [`unstable_getServerSession`](https://next-auth.js.org/configuration/nextjs#unstable_getserversession). Ne vous inquiétez pas, cette fonction est sûre à utiliser - le nom inclut "unstable" uniquement parce que l'implémentation de l'API peut changer à l'avenir. L'avantage d'utiliser `unstable_getServerSession` au lieu de `getSession` est qu'il s'agit d'une fonction côté serveur uniquement et qu'elle ne déclenche pas d'appels de récupération inutiles. `create-t3-app` crée une fonction d'assistance qui résume cette API particulière. -```ts:server/common/get-server-auth-session.ts +```ts:server/auth.ts export const getServerAuthSession = async (ctx: { req: GetServerSidePropsContext["req"]; res: GetServerSidePropsContext["res"]; @@ -84,8 +84,8 @@ export const getServerAuthSession = async (ctx: { En utilisant cette fonction d'assistance, nous pouvons récupérer la session et la transmettre au contexte tRPC : -```ts:server/trpc/context.ts -import { getServerAuthSession } from "../common/get-server-auth-session"; +```ts:server/api/trpc.ts +import { getServerAuthSession } from "../auth"; export const createContext = async (opts: CreateNextContextOptions) => { const { req, res } = opts; @@ -98,7 +98,7 @@ export const createContext = async (opts: CreateNextContextOptions) => { 2. Créez un middleware tRPC qui vérifie si l'utilisateur est authentifié. Nous utilisons ensuite le middleware dans une `protectedProcedure`. Tout appelant à ces procédures doit être authentifié, sinon une erreur sera générée qui pourra être gérée de manière appropriée par le client. -```ts:server/trpc/trpc.ts +```ts:server/api/trpc.ts const isAuthed = t.middleware(({ ctx, next }) => { if (!ctx.session || !ctx.session.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); @@ -116,7 +116,7 @@ export const protectedProcedure = t.procedure.use(isAuthed); L'objet de session est une représentation légère et minimale de l'utilisateur et ne contient que quelques champs. Lorsque vous utilisez les `protectedProcedures`, vous avez accès à l'identifiant de l'utilisateur qui peut être utilisé pour extraire plus de données de la base de données. -```ts:server/trpc/router/user.ts +```ts:server/api/routers/user.ts const userRouter = router({ me: protectedProcedure.query(async ({ ctx }) => { const user = await prisma.user.findUnique({ diff --git a/www/src/pages/fr/usage/prisma.md b/www/src/pages/fr/usage/prisma.md index 81c5d73ff8..a19b49053b 100644 --- a/www/src/pages/fr/usage/prisma.md +++ b/www/src/pages/fr/usage/prisma.md @@ -9,7 +9,7 @@ Prisma est un ORM pour TypeScript, qui vous permet de définir votre schéma et ## Prisma Client -Situé dans `/server/db/client.ts`, le client Prisma est instancié en tant que variable globale (cette façon est recommandé comme [meilleure pratique](https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices#problem) par l'équipe de Prisma) et exporté pour être utilisé dans vos routes API. Nous incluons le client Prisma dans [Context](/fr/usage/trpc#-servertrpccontextts) par défaut et recommandons de l'utiliser au lieu de l'importer séparément dans chaque fichier. +Situé dans `/server/db.ts`, le client Prisma est instancié en tant que variable globale (cette façon est recommandé comme [meilleure pratique](https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices#problem) par l'équipe de Prisma) et exporté pour être utilisé dans vos routes API. Nous incluons le client Prisma dans le [Context](/fr/usage/trpc#-servertrpccontextts) par défaut et recommandons de l'utiliser au lieu de l'importer séparément dans chaque fichier. ## Schéma @@ -39,7 +39,7 @@ La base de données par défaut est une base de données SQLite, idéale pour le ``` ```ts:prisma/seed.ts -import { prisma } from "../src/server/db/client"; +import { prisma } from "../src/server/db"; async function main() { const id = "cl9ebqhxk00003b600tymydho"; diff --git a/www/src/pages/fr/usage/trpc.md b/www/src/pages/fr/usage/trpc.md index 8205ad11ce..54806bd974 100644 --- a/www/src/pages/fr/usage/trpc.md +++ b/www/src/pages/fr/usage/trpc.md @@ -41,25 +41,29 @@ tRPC nécessite beaucoup de configuration que `create-t3-app` fait pour vous. Pa Il s'agit du point d'entrée de votre API et expose le routeur tRPC. Normalement, vous ne toucherez pas beaucoup à ce fichier, mais si vous devez, par exemple, activer le middleware CORS ou similaire, il est utile de savoir que le `createNextApiHandler` exporté est un [gestionnaire d'API Next.js](https://nextjs.org/docs/api-routes/introduction) qui prend une [requête](https://developer.mozilla.org/en-US/docs/Web/API/Request) et [réponse](https://developer.mozilla.org/en-US/docs/Web/API/Response). Cela signifie que vous pouvez envelopper le `createNextApiHandler` dans n'importe quel middleware de votre choix. Voir ci-dessous pour un [exemple] (#enabling-cors) d'ajout de CORS. -### 📄 `server/trpc/context.ts` +### 📄 `server/api/trpc.ts` -Ce fichier est l'endroit où vous définissez le contexte qui est transmis à vos procédures tRPC. Le contexte est une donnée à laquelle toutes vos procédures tRPC auront accès, et c'est un endroit idéal pour mettre des choses comme les connexions à la base de données, les informations d'authentification, etc. Dans create-t3-app, nous utilisons deux fonctions, pour activer l'utilisation d'un sous-ensemble du contexte lorsque nous n'avons pas accès à l'objet de requête. +Ce fichier est divisé en deux parties, la création du contexte et l'initialisation de tRPC : -- `createContextInner`: C'est ici que vous définissez le contexte qui ne dépend pas de la requête, par ex. votre connexion à la base de données. Vous pouvez utiliser cette fonction pour les [tests d'intégration](#exemple-de-test-dintégration) ou [ssg-helpers](https://trpc.io/docs/v10/ssg-helpers) où vous n'avez pas d'objet de requête. +1. Nous définissons le contexte qui est passé à vos procédures tRPC. Le contexte sont des données auxquelles toutes vos procédures tRPC auront accès, et c'est un endroit idéal pour mettre des choses comme les connexions à la base de données, les informations d'authentification, etc. Dans create-t3-app, nous utilisons deux fonctions, pour activer l'utilisation d'un sous-ensemble du contexte lorsque nous n'avons pas accès à l'objet de requête. -- `createContext`: C'est ici que vous définissez le contexte qui dépend de la requête, par ex. la session de l'utilisateur. Vous récupérez la session à l'aide de l'objet `opts.req`, puis transmettez la session à la fonction `createContextInner` pour créer le contexte final. +- `createInnerTRPCContext` : c'est ici que vous définissez le contexte qui ne dépend pas de la requête, par ex. votre connexion à la base de données. Vous pouvez utiliser cette fonction pour les [tests d'intégration](#exemple-de-test-dintégration) ou [ssg-helpers](https://trpc.io/docs/v10/ssg-helpers) où vous n'avez pas d'objet de requête . -### 📄 `server/trpc/trpc.ts` +- `createTRPCContext` : c'est ici que vous définissez le contexte qui dépend de la requête, par ex. la session de l'utilisateur. Vous demandez la session à l'aide de l'objet `opts.req`, puis transmettez la session à la fonction `createInnerTRPCContext` pour créer le contexte final. -C'est ici que vous initialisez tRPC et définissez des [procédures](https://trpc.io/docs/v10/procedures) et des [middlewares](https://trpc.io/docs/v10/middlewares) réutilisables. Par convention, vous ne devriez pas exporter l'intégralité de l'objet `t`, mais plutôt créer des procédures et des middlewares réutilisables et les exporter. +1. Nous initialisons tRPC et définissons des [procédures](https://trpc.io/docs/v10/procedures) et des [middlewares](https://trpc.io/docs/v10/middlewares) réutilisables. Par convention, vous ne devriez pas exporter l'intégralité de l'objet `t`, mais plutôt de créer des procédures et des middlewares réutilisables et de les exporter. Vous remarquerez que nous utilisons `superjson` comme [transformateur de données](https://trpc.io/docs/v10/data-transformers). Cela fait en sorte que vos types de données sont préservés lorsqu'ils atteignent le client, donc si vous envoyez par exemple un objet `Date`, le client renverra une `Date` et non une chaîne, ce qui est le cas pour la plupart des API. -### 📄 `server/trpc/router/*.ts` +### 📄 `server/api/routers/*.ts` -C'est ici que vous définissez les routes et les procédures de votre API. Par convention, vous [créez des routeurs séparés](https://trpc.io/docs/v10/router) pour les procédures associées, puis les [fusionnez](https://trpc.io/docs/v10/merging-routers) tous entre eux dans un seul routeur d'application via `server/trpc/router/_app.ts`. +C'est ici que vous définissez les routes et les procédures de votre API. Par convention, vous [créez des routeurs séparés](https://trpc.io/docs/v10/router) pour les procédures associées. -### 📄 `utils/trpc.ts` +### 📄 `server/api/root.ts` + +Ici, nous [fusionnons](https://trpc.io/docs/v10/merging-routers) tous les sous-routeurs définis dans `routers/**` en un seul routeur d'application. + +### 📄 `utils/api.ts` Il s'agit du point d'entrée frontend pour tRPC. C'est ici que vous allez importer la **définition de type** du routeur et créer votre client tRPC avec les hooks de react-query. Depuis que nous avons activé `superjson` comme transformateur de données sur le backend, nous devons également l'activer sur le frontend. En effet, les données sérialisées du backend sont désérialisées sur le frontend. @@ -77,9 +81,9 @@ Le contributeur de tRPC [trashh_dev](https://twitter.com/trashh_dev) a fait [une Avec tRPC, vous écrivez des fonctions TypeScript sur votre backend, puis vous les appelez depuis votre frontend. Une procédure tRPC simple pourrait ressembler à ceci : -```ts:server/trpc/router/user.ts -const userRouter = t.router({ - getById: t.procedure.input(z.string()).query(({ ctx, input }) => { +```ts:server/api/routers/user.ts +const userRouter = createTRPCRouter({ + getById: publicProcedure.input(z.string()).query(({ ctx, input }) => { return ctx.prisma.user.findFirst({ where: { id: input, @@ -95,8 +99,8 @@ Après l'entrée, nous enchaînons une fonction de résolveur qui peut être soi Vous définissez vos procédures dans des "routeurs" qui représentent une collection de procédures liées avec un espace de noms partagé. Vous pouvez avoir un routeur pour les `utilisateurs`, un pour les `posts` et un autre pour les `messages`. Ces routeurs peuvent ensuite être fusionnés en un seul `appRouter` centralisé : -```ts:server/trpc/router/_app.ts -const appRouter = t.router({ +```ts:server/api/root.ts +const appRouter = createTRPCRouter({ users: userRouter, posts: postRouter, messages: messageRouter, @@ -111,10 +115,11 @@ Maintenant appelons la procédure sur notre frontend. tRPC fournit un wrapper po ```tsx:pages/users/[id].tsx import { useRouter } from "next/router"; +import { api } from "../../utils/api"; const UserPage = () => { const { query } = useRouter(); - const userQuery = trpc.users.getById.useQuery(query.id); + const userQuery = api.users.getById.useQuery(query.id); return (
@@ -136,12 +141,12 @@ Si vous souhaitez exposer une seule procédure vers l'extérieur, vous cherchez ```ts:pages/api/users/[id].ts import type { NextApiRequest, NextApiResponse } from "next"; -import { appRouter } from "../../../server/trpc/router/_app"; -import { createContext } from "../../../server/trpc/context"; +import { appRouter } from "../../../server/api/root"; +import { createTRPCContext } from "../../../server/api/trpc"; const userByIdHandler = async (req: NextApiRequest, res: NextApiResponse) => { // Create context and caller - const ctx = await createContext({ req, res }); + const ctx = await createTRPCContext({ req, res }); const caller = appRouter.createCaller(ctx); try { const { id } = req.query; @@ -176,7 +181,7 @@ Comparons un endpoint d'API Next.js à une procédure tRPC. Disons que nous voul ```ts:pages/api/users/[id].ts import type { NextApiRequest, NextApiResponse } from "next"; -import { prisma } from "../../../server/db/client"; +import { prisma } from "../../../server/db"; const userByIdHandler = async (req: NextApiRequest, res: NextApiResponse) => { if (req.method !== "GET") { @@ -237,8 +242,8 @@ Si vous avez besoin de consommer votre API à partir d'un domaine différent, pa ```ts:pages/api/trpc/[trpc].ts import type { NextApiRequest, NextApiResponse } from "next"; import { createNextApiHandler } from "@trpc/server/adapters/next"; -import { appRouter } from "~/server/trpc/router/_app"; -import { createContext } from "~/server/trpc/context"; +import { appRouter } from "~/server/api/root"; +import { createTRPCContext } from "~/server/api/trpc"; import cors from "nextjs-cors"; const handler = async (req: NextApiRequest, res: NextApiResponse) => { @@ -248,7 +253,7 @@ const handler = async (req: NextApiRequest, res: NextApiResponse) => { // Create and call the tRPC handler return createNextApiHandler({ router: appRouter, - createContext, + createContext: createTRPCContext, })(req, res); }; @@ -261,10 +266,10 @@ Les mises à jour optimistes se produisent lorsque nous mettons à jour l'interf ```tsx const MyComponent = () => { - const listPostQuery = trpc.post.list.useQuery(); + const listPostQuery = api.post.list.useQuery(); - const utils = trpc.useContext(); - const postCreate = trpc.post.create.useMutation({ + const utils = api.useContext(); + const postCreate = api.post.create.useMutation({ async onMutate(newPost) { // Cancel outgoing fetches (so they don't overwrite our optimistic update) await utils.post.list.cancel(); @@ -296,12 +301,12 @@ Voici un exemple de test d'intégration qui utilise [Vitest](https://vitest.dev) ```ts import { type inferProcedureInput } from "@trpc/server"; -import { createContextInner } from "~/server/router/context"; -import { appRouter, type AppRouter } from "~/server/router/_app"; +import { createInnerTRPCContext } from "~/server/api/trpc"; +import { appRouter, type AppRouter } from "~/server/api/root"; import { expect, test } from "vitest"; test("example router", async () => { - const ctx = await createContextInner({ session: null }); + const ctx = await createInnerTRPCContext({ session: null }); const caller = appRouter.createCaller(ctx); type Input = inferProcedureInput;