diff --git a/public/images/docs/diagrams/use_client_module_dependency.dark.png b/public/images/docs/diagrams/use_client_module_dependency.dark.png new file mode 100644 index 000000000..c50e7308b Binary files /dev/null and b/public/images/docs/diagrams/use_client_module_dependency.dark.png differ diff --git a/public/images/docs/diagrams/use_client_module_dependency.png b/public/images/docs/diagrams/use_client_module_dependency.png new file mode 100644 index 000000000..d535246f7 Binary files /dev/null and b/public/images/docs/diagrams/use_client_module_dependency.png differ diff --git a/public/images/docs/diagrams/use_client_render_tree.dark.png b/public/images/docs/diagrams/use_client_render_tree.dark.png new file mode 100644 index 000000000..8d3e6a484 Binary files /dev/null and b/public/images/docs/diagrams/use_client_render_tree.dark.png differ diff --git a/public/images/docs/diagrams/use_client_render_tree.png b/public/images/docs/diagrams/use_client_render_tree.png new file mode 100644 index 000000000..ad3840681 Binary files /dev/null and b/public/images/docs/diagrams/use_client_render_tree.png differ diff --git a/src/components/Layout/getRouteMeta.tsx b/src/components/Layout/getRouteMeta.tsx index d22947847..3564dd738 100644 --- a/src/components/Layout/getRouteMeta.tsx +++ b/src/components/Layout/getRouteMeta.tsx @@ -58,13 +58,13 @@ export interface RouteMeta { order?: number; } -type TravesalContext = RouteMeta & { +type TraversalContext = RouteMeta & { currentIndex: number; }; export function getRouteMeta(cleanedPath: string, routeTree: RouteItem) { const breadcrumbs = getBreadcrumbs(cleanedPath, routeTree); - const ctx: TravesalContext = { + const ctx: TraversalContext = { currentIndex: 0, }; buildRouteMeta(cleanedPath, routeTree, ctx); @@ -79,7 +79,7 @@ export function getRouteMeta(cleanedPath: string, routeTree: RouteItem) { function buildRouteMeta( searchPath: string, currentRoute: RouteItem, - ctx: TravesalContext + ctx: TraversalContext ) { ctx.currentIndex++; diff --git a/src/content/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023.md b/src/content/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023.md index eb58a8140..b205b64e8 100644 --- a/src/content/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023.md +++ b/src/content/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023.md @@ -72,12 +72,11 @@ Le noyau du compilateur est presque entièrement découplé de Babel, et l'API n Lors des refontes du compilateur de ces derniers mois, nous nous sommes concentrés sur l'affinage du modèle noyau de compilation pour garantir que nous pouvions gérer des complexités telles que les conditionnels, les boucles, la réaffectation et les mutations. Ceci dit, JavaScript offre de nombreuses manières d'exprimer chacun de ces points : `if`/`else`, les ternaires, `for`, `for-in`, `for-of`, etc. Si nous avions voulu prendre en charge l'intégralité du langage d'entrée de jeu, nous aurions trop retardé le point de validation du modèle noyau. Nous avons choisi de plutôt commencer avec un sous-ensemble représentatif du language : `let`/`const`, `if`/`else`, les boucles `for`, les objets, les tableaux, les primitives, les appels de fonctions et quelques autres fonctionnalités. Au fur et à mesure que nous gagnions en confiance dans notre modèle noyau et que nous en affinions les abstractions internes, nous avons étendu le sous-ensemble pris en charge. Nous indiquons de façon explicite les parties de la syntaxe que nous ne prenons pas encore en charge, en maintenant des journaux de diagnostic et en sautant la compilation des sources non prises en charge. Nous avons des utilitaires pour essayer le compilateur sur les bases de code de Meta et voir quels aspects non encore pris en charge sont les plus couramment utilisés, pour prioriser les évolutions à venir. Nous allons continuer à étendre progressivement tout ça jusqu'à prendre en charge l'intégralité du langage. - Pour permettre à du code JavaScript classique d'être réactif dans des composants React, il faut que le compilateur ait une compréhension profonde de sa sémantique pour déterminer précisément ce que fait ce code. En adoptant cette approche, nous avons créé un système de réactivité en JavaScript qui vous permet d'écrire du code métier de quelque complexité que ce soit, en bénéficiant de la pleine expressivité du langage, plutôt que de vous limiter à un langage taillé sur-mesure. ## Rendu hors-écran {/*offscreen-rendering*/} -Le rendu hors-écran *(offscreen rendering, NdT)* désigne la possibilité prochaine pour React de calculer les rendus de vos écrans en arrière-plan, sans nuire aux performances. Vous pouvez y penser comme à une variation de la [propriété CSS `content-visiblity`](https://developer.mozilla.org/fr/docs/Web/CSS/content-visibility), qui ne fonctionnerait pas seulement pour les éléments du DOM mais aussi pour les composants React. Au fil de nos recherches, nous avons découvert plusieurs scénarios d'utilisation : +Le rendu hors-écran *(offscreen rendering, NdT)* désigne la possibilité prochaine pour React de calculer les rendus de vos écrans en arrière-plan, sans nuire aux performances. Vous pouvez y penser comme à une variation de la [propriété CSS `content-visibility`](https://developer.mozilla.org/fr/docs/Web/CSS/content-visibility), qui ne fonctionnerait pas seulement pour les éléments du DOM mais aussi pour les composants React. Au fil de nos recherches, nous avons découvert plusieurs scénarios d'utilisation : - Un routeur pourrait précalculer le rendu d'écrans en arrière-plan pour que lorsque l'utilisateur navigue vers l'un d'eux, il soit immédiatement disponible. - Un composant d'onglets pourrait préserver l'état d'onglets masqués, pour que lorsque l'utilisateur rebascule dessus, il ne perde pas sa progression. diff --git a/src/content/reference/react/Component.md b/src/content/reference/react/Component.md index 3b667d170..7b844b14e 100644 --- a/src/content/reference/react/Component.md +++ b/src/content/reference/react/Component.md @@ -635,7 +635,7 @@ class Form extends Component { return ( <> -

Salut {this.state.name}. +

Salut {this.state.name}.

); } diff --git a/src/content/reference/react/directives.md b/src/content/reference/react/directives.md index 4ab526a1e..2ceb9fad0 100644 --- a/src/content/reference/react/directives.md +++ b/src/content/reference/react/directives.md @@ -19,5 +19,5 @@ Les directives fournissent des instructions à destination des [*bundlers* compa ## Directives dans le code source {/*source-code-directives*/} -* [`'use client'`](/reference/react/use-client) marque les fichiers sources dont les composants s'exécutent côté client. +* [`'use client'`](/reference/react/use-client) vous permet d'indiquer quel code est exécuté côté client. * [`'use server'`](/reference/react/use-server) marque les fonctions côté serveur qui peuvent être appelées par du code côté client. diff --git a/src/content/reference/react/hooks.md b/src/content/reference/react/hooks.md new file mode 100644 index 000000000..3aa91a75c --- /dev/null +++ b/src/content/reference/react/hooks.md @@ -0,0 +1,140 @@ +--- +title: "Hooks fournis par React" +--- + + + +Les *Hooks* vous permettent d’utiliser différentes fonctionnalités de React au sein de vos composants. Vous pouvez utiliser les Hooks pré-fournis ou les associer pour créer les vôtres. Cette page liste tout les Hooks fournis par React. + + + +--- + +## Hooks d’état local {/*state-hooks*/} + +*L’état local* permet à un composant de [« se souvenir » d’informations telles que des saisies utilisateur](/learn/state-a-components-memory). Par exemple, un composant formulaire peut utiliser l’état local pour stocker la valeur saisie, alors qu’un composant de galerie d’images pourra l’utiliser pour stocker l’index de l’image affichée. + +Pour ajouter un état local à un composant, utilisez un de ces Hooks : + +* [`useState`](/reference/react/useState) déclare un état local que vous pouvez mettre à jour directement. +* [`useReducer`](/reference/react/useReducer) déclare un état local dont la logique de mise à jour réside dans une [fonction réducteur](/learn/extracting-state-logic-into-a-reducer). + +```js +function ImageGallery() { + const [index, setIndex] = useState(0); + // ... +``` + +--- + +## Hooks de Contexte {/*context-hooks*/} + +Le *Contexte* permet à un composant [de recevoir des informations de parents éloignés sans avoir à passer par ses props](/learn/passing-props-to-a-component). Par exemple, le composant de niveau racine de votre appli peut passer le thème de l’interface utilisateur (UI) à tous les composants qu’elle contient, à quelque profondeur que ce soit. + +* [`useContext`](/reference/react/useContext) s’abonne à un contexte et le lit. + +```js +function Button() { + const theme = useContext(ThemeContext); + // ... +``` + +--- + +## Hooks de Ref {/*ref-hooks*/} + +Les *Refs* permettent à un composant [de conserver certaines informations qui ne sont pas utilisées pour faire le rendu](/learn/referencing-values-with-refs), comme un nœud DOM ou un ID de timer. Contrairement à l’état local, la mise à jour d’une Ref ne déclenche pas un nouveau rendu de votre composant. Les Refs sont une « échappatoire » du paradigme de React. Elles sont utiles lorsque vous devez travailler avec des systèmes externes à React, telles que les API du navigateur web. + +* [`useRef`](/reference/react/useRef) déclare une Ref. Vous pouvez y stocker n’importe quelle valeur, mais elle est le plus souvent utilisée pour référencer un nœud du DOM. + +* [`useImperativeHandle`](/reference/react/useImperativeHandle) vous permet de personnaliser la Ref exposée par votre composant. Ce Hook est rarement utilisé. + +```js +function Form() { + const inputRef = useRef(null); + // ... +``` + +--- + +## Hooks d’effets {/*effect-hooks*/} + +Les *Effets* permettent à un composant [de se connecter et de se synchroniser avec des systèmes extérieurs](/learn/synchronizing-with-effects). Il peut notamment s’agir du réseau, du DOM, des animations, d’éléments d’interface écrits en utilisant une autre bibliothèque, et d’autres codes non React. + +* [`useEffect`](/reference/react/useEffect) connecte un composant à un système extérieur. + +```js +function ChatRoom({ roomId }) { + useEffect(() => { + const connection = createConnection(roomId); + connection.connect(); + return () => connection.disconnect(); + }, [roomId]); + // ... +``` + +Les Effets sont une « échappatoire » du paradigme de React. N’utilisez pas les Effets pour orchestrer le flux de données de votre application. Si vous n’interagissez pas avec un système extérieur, [vous n’avez pas forcément besoin d’un Effet](/learn/you-might-not-need-an-effect). + +Il existe deux variantes rarement utilisées de `useEffect` avec des différences de timing : + +* [`useLayoutEffect`](/reference/react/useLayoutEffect) se déclenche avant que le navigateur ne repeigne l’écran. Vous pouvez y mesurer la mise en page, notamment les dimensions. +* [`useInsertionEffect`](/reference/react/useInsertionEffect) se déclenche avant que React ne fasse des changements dans le DOM. Les bibliothèques peuvent y insérer des CSS dynamiques. + +--- + +## Les Hooks de performance {/*performance-hooks*/} + +Une manière courante d’optimiser la performance de réaffichage consiste à s’épargner des tâches superflues. Par exemple, vous pouvez demander à React de réutiliser un calcul mis en cache ou d’éviter un nouveau rendu si la donnée n’a pas changé depuis le rendu précédent. + +Pour éviter les calculs coûteux et les réaffichages inutiles, utilisez l’un de ces Hooks : + +* [`useMemo`](/reference/react/useMemo) vous permet de mettre en cache le résultat d’un calcul coûteux. +* [`useCallback`](/reference/react/useCallback) vous permet de mettre en cache la définition d’une fonction avant de la passer à un composant optimisé. + +```js +function TodoList({ todos, tab, theme }) { + const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]); + // ... +} +``` + +Parfois, vous ne pouvez pas éviter le réaffichage parce que la vue doit effectivement être mise à jour. Dans ce cas, vous pouvez améliorer la performance en séparant les mises à jour bloquantes qui doivent être synchrones (comme la gestion d’une saisie dans un champ) des mises à jour non bloquantes, qui ne gèlent pas le traitement de l’interface (comme la mise à jour d’un graphique). + +Pour établir des priorités de rendu, utilisez un de ces Hooks : + +* [`useTransition`](/reference/react/useTransition) permet de marquer une transition d’état local comme non bloquante ce qui autorise d’autres mises à jour à l’interrompre. +* [`useDeferredValue`](/reference/react/useDeferredValue) vous permet de différer la mise à jour d’une partie non critique de l’UI et de laisser les autres parties se mettre à jour en premier. + +--- + +## Les Hooks de gestion de ressources {/*resource-hooks*/} + +Un composant peut accéder à des *ressources* sans qu'elles fassent partie de son état. Un composant peut par exemple lire un message depuis une promesse, ou lire des informations de styles depuis un contexte. + +Pour lire une valeur depuis une ressource, utilisez ce Hook : + +- [`use`](/reference/react/use) vous permet de lire une valeur depuis une ressource telle qu'une [promesse](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Promise) (`Promise`) ou un [contexte](/learn/passing-data-deeply-with-context). + +```js +function MessageComponent({ messagePromise }) { + const message = use(messagePromise); + const theme = use(ThemeContext); + // ... +} +``` + +--- + +## Autres Hooks {/*other-hooks*/} + +Ces Hooks sont majoritairement utiles aux auteur·e·s de bibliothèque et ne sont pas couramment utilisés dans du code applicatif. + +* [`useDebugValue`](/reference/react/useDebugValue) vous permet de personnaliser le libellé que les outils de développement React affichent pour votre propre Hook. +* [`useId`](/reference/react/useId) permet à un composant de s’associer un ID unique. Généralement utilisé avec les API d’accessibilité. +* [`useSyncExternalStore`](/reference/react/useSyncExternalStore) permet à un composant de s’abonner à une source de données extérieure. + +--- + +## Vos propres Hooks {/*your-own-hooks*/} + +Vous pouvez [définir vos propres Hooks personnalisés](/learn/reusing-logic-with-custom-hooks#extracting-your-own-custom-hook-from-a-component) au moyen de fonctions JavaScript. diff --git a/src/content/reference/react/index.md b/src/content/reference/react/index.md index 3aa91a75c..2623f9d2c 100644 --- a/src/content/reference/react/index.md +++ b/src/content/reference/react/index.md @@ -1,140 +1,35 @@ --- -title: "Hooks fournis par React" +title: Référence API React --- -Les *Hooks* vous permettent d’utiliser différentes fonctionnalités de React au sein de vos composants. Vous pouvez utiliser les Hooks pré-fournis ou les associer pour créer les vôtres. Cette page liste tout les Hooks fournis par React. +Cette section fournit une documentation de référence détaillée pour travailler avec React. +Pour une introduction à React, consultez plutôt la section [Apprendre](/learn). ---- - -## Hooks d’état local {/*state-hooks*/} - -*L’état local* permet à un composant de [« se souvenir » d’informations telles que des saisies utilisateur](/learn/state-a-components-memory). Par exemple, un composant formulaire peut utiliser l’état local pour stocker la valeur saisie, alors qu’un composant de galerie d’images pourra l’utiliser pour stocker l’index de l’image affichée. - -Pour ajouter un état local à un composant, utilisez un de ces Hooks : - -* [`useState`](/reference/react/useState) déclare un état local que vous pouvez mettre à jour directement. -* [`useReducer`](/reference/react/useReducer) déclare un état local dont la logique de mise à jour réside dans une [fonction réducteur](/learn/extracting-state-logic-into-a-reducer). - -```js -function ImageGallery() { - const [index, setIndex] = useState(0); - // ... -``` - ---- - -## Hooks de Contexte {/*context-hooks*/} - -Le *Contexte* permet à un composant [de recevoir des informations de parents éloignés sans avoir à passer par ses props](/learn/passing-props-to-a-component). Par exemple, le composant de niveau racine de votre appli peut passer le thème de l’interface utilisateur (UI) à tous les composants qu’elle contient, à quelque profondeur que ce soit. - -* [`useContext`](/reference/react/useContext) s’abonne à un contexte et le lit. - -```js -function Button() { - const theme = useContext(ThemeContext); - // ... -``` - ---- - -## Hooks de Ref {/*ref-hooks*/} - -Les *Refs* permettent à un composant [de conserver certaines informations qui ne sont pas utilisées pour faire le rendu](/learn/referencing-values-with-refs), comme un nœud DOM ou un ID de timer. Contrairement à l’état local, la mise à jour d’une Ref ne déclenche pas un nouveau rendu de votre composant. Les Refs sont une « échappatoire » du paradigme de React. Elles sont utiles lorsque vous devez travailler avec des systèmes externes à React, telles que les API du navigateur web. - -* [`useRef`](/reference/react/useRef) déclare une Ref. Vous pouvez y stocker n’importe quelle valeur, mais elle est le plus souvent utilisée pour référencer un nœud du DOM. - -* [`useImperativeHandle`](/reference/react/useImperativeHandle) vous permet de personnaliser la Ref exposée par votre composant. Ce Hook est rarement utilisé. - -```js -function Form() { - const inputRef = useRef(null); - // ... -``` - ---- - -## Hooks d’effets {/*effect-hooks*/} - -Les *Effets* permettent à un composant [de se connecter et de se synchroniser avec des systèmes extérieurs](/learn/synchronizing-with-effects). Il peut notamment s’agir du réseau, du DOM, des animations, d’éléments d’interface écrits en utilisant une autre bibliothèque, et d’autres codes non React. +La documentation de référence React est découpée en plusieurs groupes de fonctionnalités : -* [`useEffect`](/reference/react/useEffect) connecte un composant à un système extérieur. +## React {/*react*/} -```js -function ChatRoom({ roomId }) { - useEffect(() => { - const connection = createConnection(roomId); - connection.connect(); - return () => connection.disconnect(); - }, [roomId]); - // ... -``` +Les fonctionnalités programmatiques de React : -Les Effets sont une « échappatoire » du paradigme de React. N’utilisez pas les Effets pour orchestrer le flux de données de votre application. Si vous n’interagissez pas avec un système extérieur, [vous n’avez pas forcément besoin d’un Effet](/learn/you-might-not-need-an-effect). +* [Hooks](/reference/react/hooks) - Pour utiliser diverses fonctionnalités de React au sein de vos composants. +* [Composants](/reference/react/components) - Détaille les composants fournis par React que vous pouvez utiliser dans votre JSX. +* [Fonctions](/reference/react/apis) - Fonctions de l'API utiles pour définir vos composants. +* [Directives](/reference/react/directives) - Fournit des instructions aux *bundlers* compatibles avec React Server Components. -Il existe deux variantes rarement utilisées de `useEffect` avec des différences de timing : +## React DOM {/*react-dom*/} -* [`useLayoutEffect`](/reference/react/useLayoutEffect) se déclenche avant que le navigateur ne repeigne l’écran. Vous pouvez y mesurer la mise en page, notamment les dimensions. -* [`useInsertionEffect`](/reference/react/useInsertionEffect) se déclenche avant que React ne fasse des changements dans le DOM. Les bibliothèques peuvent y insérer des CSS dynamiques. +React-DOM comprend les fonctionnalités qui ne sont prises en charge que pour les applications web (celles qui tournent dans un environnement DOM navigateur). Cette section comprend les parties suivantes : ---- - -## Les Hooks de performance {/*performance-hooks*/} - -Une manière courante d’optimiser la performance de réaffichage consiste à s’épargner des tâches superflues. Par exemple, vous pouvez demander à React de réutiliser un calcul mis en cache ou d’éviter un nouveau rendu si la donnée n’a pas changé depuis le rendu précédent. - -Pour éviter les calculs coûteux et les réaffichages inutiles, utilisez l’un de ces Hooks : - -* [`useMemo`](/reference/react/useMemo) vous permet de mettre en cache le résultat d’un calcul coûteux. -* [`useCallback`](/reference/react/useCallback) vous permet de mettre en cache la définition d’une fonction avant de la passer à un composant optimisé. - -```js -function TodoList({ todos, tab, theme }) { - const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]); - // ... -} -``` - -Parfois, vous ne pouvez pas éviter le réaffichage parce que la vue doit effectivement être mise à jour. Dans ce cas, vous pouvez améliorer la performance en séparant les mises à jour bloquantes qui doivent être synchrones (comme la gestion d’une saisie dans un champ) des mises à jour non bloquantes, qui ne gèlent pas le traitement de l’interface (comme la mise à jour d’un graphique). - -Pour établir des priorités de rendu, utilisez un de ces Hooks : - -* [`useTransition`](/reference/react/useTransition) permet de marquer une transition d’état local comme non bloquante ce qui autorise d’autres mises à jour à l’interrompre. -* [`useDeferredValue`](/reference/react/useDeferredValue) vous permet de différer la mise à jour d’une partie non critique de l’UI et de laisser les autres parties se mettre à jour en premier. - ---- - -## Les Hooks de gestion de ressources {/*resource-hooks*/} - -Un composant peut accéder à des *ressources* sans qu'elles fassent partie de son état. Un composant peut par exemple lire un message depuis une promesse, ou lire des informations de styles depuis un contexte. - -Pour lire une valeur depuis une ressource, utilisez ce Hook : - -- [`use`](/reference/react/use) vous permet de lire une valeur depuis une ressource telle qu'une [promesse](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Promise) (`Promise`) ou un [contexte](/learn/passing-data-deeply-with-context). - -```js -function MessageComponent({ messagePromise }) { - const message = use(messagePromise); - const theme = use(ThemeContext); - // ... -} -``` - ---- - -## Autres Hooks {/*other-hooks*/} - -Ces Hooks sont majoritairement utiles aux auteur·e·s de bibliothèque et ne sont pas couramment utilisés dans du code applicatif. - -* [`useDebugValue`](/reference/react/useDebugValue) vous permet de personnaliser le libellé que les outils de développement React affichent pour votre propre Hook. -* [`useId`](/reference/react/useId) permet à un composant de s’associer un ID unique. Généralement utilisé avec les API d’accessibilité. -* [`useSyncExternalStore`](/reference/react/useSyncExternalStore) permet à un composant de s’abonner à une source de données extérieure. - ---- +* [Hooks](/reference/react-dom/hooks) - Les Hooks dédiés aux applications web s'exécutant dans un environnement DOM navigateur. +* [Composants](/reference/react-dom/components) - React prend en charge tous les composants natifs du navigateur pour HTML et SVG. +* [Fonctions](/reference/react-dom) - Le module `react-dom` fournit les fonctions dédiées aux applications web. +* [Fonctions côté client](/reference/react-dom/client) - L'API dans `react-dom/client` vous permet d'effectuer le rendu de composants React côté client (dans le navigateur). +* [Fonctions côté serveur](/reference/react-dom/server) - L'API dans `react-dom/server` vous permet d'effectuer le rendu de composants React côté serveur, vers du HTML. -## Vos propres Hooks {/*your-own-hooks*/} +## API React historique {/*legacy-apis*/} -Vous pouvez [définir vos propres Hooks personnalisés](/learn/reusing-logic-with-custom-hooks#extracting-your-own-custom-hook-from-a-component) au moyen de fonctions JavaScript. +* [API React historique](/reference/react/legacy) - Ces fonctions sont présentes dans le module `react`, mais leur utilisation est découragée pour tout nouveau code. diff --git a/src/content/reference/react/use-client.md b/src/content/reference/react/use-client.md index 778bbad54..3178c43d7 100644 --- a/src/content/reference/react/use-client.md +++ b/src/content/reference/react/use-client.md @@ -13,7 +13,7 @@ canary: true -`'use client'` marque les fichiers sources dont les composants s'exécutent côté client. +`'use client'` vous permet d'indiquer quel code est exécuté côté client. @@ -25,40 +25,357 @@ canary: true ### `'use client'` {/*use-client*/} -Ajoutez `'use client';` tout en haut d'un fichier pour indiquer que ce fichier (ainsi que tout composant enfant qu'il utilise) s'exécute coté client, indépendamment des endroits qui l'importent. +Ajoutez `'use client';` tout en haut d'un fichier pour indiquer que ce fichier (ainsi que tout composant enfant qu'il utilise) s'exécute coté client. -```js +```js {1} 'use client'; import { useState } from 'react'; +import { formatDate } from './formatters'; +import Button from './button'; -export default function RichTextEditor(props) { +export default function RichTextEditor({ timestamp, text }) { + const date = formatDate(timestamp); + // ... + const editButton = + {children} + + ); +} +``` + +```js Copyright.js +export default function Copyright({year}) { + return

©️ {year}

; +} +``` + +```js inspirations.js +export default [ + "Don’t let yesterday take up too much of today.” — Will Rogers", + "Ambition is putting a ladder against the sky.", + "A joy that's shared is a joy made double.", +]; +``` + +```css +.fancy { + font-family: 'Georgia'; +} +.title { + color: #007AA3; + text-decoration: underline; +} +.cursive { + font-style: italic; +} +.small { + font-size: 10px; +} +``` + + + +In the module dependency tree of this example app, the `'use client'` directive in `InspirationGenerator.js` marks that module and all of its transitive dependencies as client modules. The subtree starting at `InspirationGenerator.js` is now marked as client modules. + + +`'use client'` segments the module dependency tree of the React Server Components app, marking `InspirationGenerator.js` and all of its dependencies as client-rendered. + + +During render, the framework will server-render the root component and continue through the [render tree](/learn/understanding-your-ui-as-a-tree#the-render-tree), opting-out of evaluating any code imported from client-marked code. + +The server-rendered portion of the render tree is then sent to the client. The client, with its client code downloaded, then completes rendering the rest of the tree. + + +The render tree for the React Server Components app. `InspirationGenerator` and its child component `FancyText` are components exported from client-marked code and considered Client Components. + + +We introduce the following definitions: + +* **Client Components** are components in a render tree that are rendered on the client. +* **Server Components** are components in a render tree that are rendered on the server. + +Working through the example app, `App`, `FancyText` and `Copyright` are all server-rendered and considered Server Components. As `InspirationGenerator.js` and its transitive dependencies are marked as client code, the component `InspirationGenerator` and its child component `FancyText` are Client Components. + + + +#### How is `FancyText` both a Server and a Client Component? {/*how-is-fancytext-both-a-server-and-a-client-component*/} + +By the above definitions, the component `FancyText` is both a Server and Client Component, how can that be? + +First, let's clarify that the term "component" is not very precise. Here are just two ways "component" can be understood: + +1. A "component" can refer to a **component definition**. In most cases this will be a function. + +```js +// This is a definition of a component +function MyComponent() { + return

My Component

+} +``` + +2. A "component" can also refer to a **component usage** of its definition. +```js +import MyComponent from './MyComponent'; + +function App() { + // This is a usage of a component + return ; +} +``` + +Often, the imprecision is not important when explaining concepts, but in this case it is. + +When we talk about Server or Client Components, we are referring to component usages. + +* If the component is defined in a module with a `'use client'` directive, or the component is imported and called in a Client Component, then the component usage is a Client Component. +* Otherwise, the component usage is a Server Component. + + +A render tree illustrates component usages. + +Back to the question of `FancyText`, we see that the component definition does _not_ have a `'use client'` directive and it has two usages. -## Utilisation {/*usage*/} +The usage of `FancyText` as a child of `App`, marks that usage as a Server Component. When `FancyText` is imported and called under `InspirationGenerator`, that usage of `FancyText` is a Client Component as `InspirationGenerator` contains a `'use client'` directive. + +This means that the component definition for `FancyText` will both be evaluated on the server and also downloaded by the client to render its Client Component usage. + + + + + +#### Why is `Copyright` a Server Component? {/*why-is-copyright-a-server-component*/} + +Because `Copyright` is rendered as a child of the Client Component `InspirationGenerator`, you might be surprised that it is a Server Component. + +Recall that `'use client'` defines the boundary between server and client code on the _module dependency tree_, not the render tree. + + +`'use client'` defines the boundary between server and client code on the module dependency tree. + + +In the module dependency tree, we see that `App.js` imports and calls `Copyright` from the `Copyright.js` module. As `Copyright.js` does not contain a `'use client'` directive, the component usage is rendered on the server. `App` is rendered on the server as it is the root component. + +Client Components can render Server Components because you can pass JSX as props. In this case, `InspirationGenerator` receives `Copyright` as [children](/learn/passing-props-to-a-component#passing-jsx-as-children). However, the `InspirationGenerator` module never directly imports the `Copyright` module nor calls the component, all of that is done by `App`. In fact, the `Copyright` component is fully executed before `InspirationGenerator` starts rendering. + +The takeaway is that a parent-child render relationship between components does not guarantee the same render environment. + + + +### When to use `'use client'` {/*when-to-use-use-client*/} + +With `'use client'`, you can determine when components are Client Components. As Server Components are default, here is a brief overview of the advantages and limitations to Server Components to determine when you need to mark something as client rendered. + +For simplicity, we talk about Server Components, but the same principles apply to all code in your app that is server run. + +#### Advantages of Server Components {/*advantages*/} +* Server Components can reduce the amount of code sent and run by the client. Only client modules are bundled and evaluated by the client. +* Server Components benefit from running on the server. They can access the local filesystem and may experience low latency for data fetches and network requests. + +#### Limitations of Server Components {/*limitations*/} +* Server Components cannot support interaction as event handlers must be registered and triggered by a client. + * For example, event handlers like `onClick` can only be defined in Client Components. +* Server Components cannot use most Hooks. + * When Server Components are rendered, their output is essentially a list of components for the client to render. Server Components do not persist in memory after render and cannot have their own state. + +### Serializable types returned by Server Components {/*serializable-types*/} + +As in any React app, parent components pass data to child components. As they are rendered in different environments, passing data from a Server Component to a Client Component requires extra consideration. + +Prop values passed from a Server Component to Client Component must be serializable. + +Serializable props include: +* Primitives + * [string](https://developer.mozilla.org/en-US/docs/Glossary/String) + * [number](https://developer.mozilla.org/en-US/docs/Glossary/Number) + * [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) + * [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean) + * [undefined](https://developer.mozilla.org/en-US/docs/Glossary/Undefined) + * [null](https://developer.mozilla.org/en-US/docs/Glossary/Null) + * [symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), only symbols registered in the global Symbol registry via [`Symbol.for`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for) +* Iterables containing serializable values + * [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) + * [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) + * [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) + * [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) + * [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) and [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) +* [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) +* Plain [objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object): those created with [object initializers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer), with serializable properties +* Functions that are [server actions](/reference/react/use-server) +* Client or Server Component elements (JSX) +* [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) + +Notably, these are not supported: +* [Functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) that are not exported from client-marked modules or marked with [`'use server'`](/reference/react/use-server) +* [Classes](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Classes_in_JavaScript) +* Objects that are instances of any class (other than the built-ins mentioned) or objects with [a null prototype](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects) +* Symbols not registered globally, ex. `Symbol('my new symbol')` + + +## Usage {/*usage*/} + +### Building with interactivity and state {/*building-with-interactivity-and-state*/} + + + +```js App.js +'use client'; + +import { useState } from 'react'; + +export default function Counter({initialValue = 0}) { + const [countValue, setCountValue] = useState(initialValue); + const increment = () => setCountValue(countValue + 1); + const decrement = () => setCountValue(countValue - 1); + return ( + <> +

Count Value: {countValue}

+ + + + ); +} +``` + + + +As `Counter` requires both the `useState` hook and event handlers to increment or decrement the value, this component must be a Client Component and will require a `'use client'` directive at the top. + +In contrast, a component that renders UI without interaction will not need to be a Client Component. + +```js +import { readFile } from 'node:fs/promises'; +import Counter from './Counter'; + +export default async function CounterContainer() { + const initialValue = await readFile('/path/to/counter_value'); + return +} +``` + +For example, `Counter`'s parent component, `CounterContainer`, does not require `'use client'` as it is not interactive and does not use state. In addition, `CounterContainer` must be a Server Component as it reads from the local file system on the server, which is possible only in a Server Component. + +There are also components that don't use any server or client-only features and can be agnostic to where they render. In our earlier example, `FancyText` is one such component. + +```js +export default function FancyText({title, text}) { + return title + ?

{text}

+ :

{text}

+} +``` + +In this case, we don't add the `'use client'` directive, resulting in `FancyText`'s _output_ (rather than its source code) to be sent to the browser when referenced from a Server Component. As demonstrated in the earlier Inspirations app example, `FancyText` is used as both a Server or Client Component, depending on where it is imported and used. + +But if `FancyText`'s HTML output was large relative to its source code (including dependencies), it might be more efficient to force it to always be a Client Component. Components that return a long SVG path string are one case where it may be more efficient to force a component to be a Client Component. + +### Using client APIs {/*using-client-apis*/} + +Your React app may use client-specific APIs, such as the browser's APIs for web storage, audio and video manipulation, and device hardware, among [others](https://developer.mozilla.org/en-US/docs/Web/API). + +In this example, the component uses [DOM APIs](https://developer.mozilla.org/en-US/docs/Glossary/DOM) to manipulate a [`canvas`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas) element. Since those APIs are only available in the browser, it must be marked as a Client Component. + +```js +'use client'; + +import {useRef, useEffect} from 'react'; + +export default function Circle() { + const ref = useRef(null); + useLayoutEffect(() => { + const canvas = ref.current; + const context = canvas.getContext('2d'); + context.reset(); + context.beginPath(); + context.arc(100, 75, 50, 0, 2 * Math.PI); + context.stroke(); + }); + return ; +} +``` - +### Using third-party libraries {/*using-third-party-libraries*/} -Cette section est en cours de rédaction. +Often in a React app, you'll leverage third-party libraries to handle common UI patterns or logic. -Cette API peut être utilisée par n'importe quel framework prenant en charge les React Server Components. Ces frameworks vous fourniront davantage de documentation. +These libraries may rely on component Hooks or client APIs. Third-party components that use any of the following React APIs must run on the client: +* [createContext](/reference/react/createContext) +* [`react`](/reference/react/hooks) and [`react-dom`](/reference/react-dom/hooks) Hooks, excluding [`use`](/reference/react/use) and [`useId`](/reference/react/useId) +* [forwardRef](/reference/react/forwardRef) +* [memo](/reference/react/memo) +* [startTransition](/reference/react/startTransition) +* If they use client APIs, ex. DOM insertion or native platform views -* [Documentation Next.js](https://nextjs.org/docs/getting-started/react-essentials) -* D'autres arrivent prochainement +If these libraries have been updated to be compatible with React Server Components, then they will already include `'use client'` markers of their own, allowing you to use them directly from your Server Components. If a library hasn't been updated, or if a component needs props like event handlers that can only be specified on the client, you may need to add your own Client Component file in between the third-party Client Component and your Server Component where you'd like to use it. - +[TODO]: <> (Troubleshooting - need use-cases) diff --git a/src/content/reference/react/use-server.md b/src/content/reference/react/use-server.md index 8d18fca78..572969ac2 100644 --- a/src/content/reference/react/use-server.md +++ b/src/content/reference/react/use-server.md @@ -25,37 +25,191 @@ canary: true ### `'use server'` {/*use-server*/} -Ajoutez `'use server';` tout en haut d'une fonction asynchrone pour indiquer que cette fonction peut être appelée par du code côté client. +Ajoutez `'use server';` tout en haut d'une fonction asynchrone pour indiquer que cette fonction peut être appelée par du code côté client. Nous appelons ces fonctions des _actions serveur_. -```js +```js {2} async function addToCart(data) { 'use server'; // ... } - -// ``` -Cette fonction peut être passée au client. Lorsqu'elle est appelée par le client, elle fera un appel réseau au serveur en lui passant une copie sérialisée des arguments qu'elle a reçus. Si la fonction serveur renvoie une valeur, celle-ci sera sérialisée et renvoyée au client. +When calling a server action on the client, it will make a network request to the server that includes a serialized copy of any arguments passed. If the server action returns a value, that value will be serialized and returned to the client. -Vous pouvez aussi utiliser `'use server';` tout en haut d'un fichier pour indiquer que tous les exports de ce fichier sont des fonctions serveur asynchrones qui peuvent être utilisées depuis n'importe où, y compris par import dans des fichiers de composants côté client. +Instead of individually marking functions with `'use server'`, you can add the directive to the top of a file to mark all exports within that file as server actions that can be used anywhere, including imported in client code. #### Limitations {/*caveats*/} -* Gardez à l'esprit que les paramètres des fonctions marquées par `'use server'` sont entièrement contrôlés par le client. Pour une meilleure sécurité, traitez-les toujours commes des entrées non vérifiées, et assurez-vous de les valider et d'en échapper le contenu lorsque nécessaire. -* Pour éviter toute confusion qui pourrait résulter du mélange entre codes côté client et côté serveur au sein d'un même fichier, `'use server'` ne peut être utilisée que dans des fichiers côté serveur. Les fonctions résultantes peuvent être passées à des composants côté client *via* leurs props. -* Puisque les appels réseaux sous-jacents sont intrinsèquement asynchrones, `'use server'` ne peut être utilisée que pour des fonctions asynchrones. -* Les directives telles que `'use server'` doivent être placées au tout début du fichier, au-dessus de tout import et de quelque autre code que ce soit (à l'exception des commentaires, qui peuvent apparaître avant). Elles doivent utiliser des apostrophes (`'`) ou guillemets (`"`), pas des apostrophes inverses (\`). (Le format de directive `'use xyz'` n'est pas sans rappeler la convention de nommage `useXyz()` des Hooks, mais c'est là une simple coïncidence.) +* `'use server'` must be at the very beginning of their function or module; above any other code including imports (comments above directives are OK). They must be written with single or double quotes, not backticks. +* `'use server'` can only be used in server-side files. The resulting server actions can be passed to Client Components through props. See supported [types for serialization](#serializable-parameters-and-return-values). +* To import a server action from [client code](/reference/react/use-client), the directive must be used on a module level. +* Because the underlying network calls are always asynchronous, `'use server'` can only be used on async functions. +* Always treat arguments to server actions as untrusted input and authorize any mutations. See [security considerations](#security). +* Server actions should be called in a [transition](/reference/react/useTransition). Server actions passed to [`
`](/reference/react-dom/components/form#props) or [`formAction`](/reference/react-dom/components/input#props) will automatically be called in a transition. +* Server actions are designed for mutations that update server-side state; they are not recommended for data fetching. Accordingly, frameworks implementing server actions typically process one action at a time and do not have a way to cache the return value. -## Utilisation {/*usage*/} +### Security considerations {/*security*/} - +Arguments to server actions are fully client-controlled. For security, always treat them as untrusted input, and make sure to validate and escape arguments as appropriate. + +In any server action, make sure to validate that the logged-in user is allowed to perform that action. -Cette section est en cours de rédaction. + -Cette API peut être utilisée par n'importe quel framework prenant en charge les React Server Components. Ces frameworks vous fourniront davantage de documentation. +To prevent sending sensitive data from a server action, there are experimental taint APIs to prevent unique values and objects from being passed to client code. -* [Documentation Next.js](https://nextjs.org/docs/getting-started/react-essentials) -* D'autres arrivent prochainement +See [experimental_taintUniqueValue](/reference/react/experimental_taintUniqueValue) and [experimental_taintObjectReference](/reference/react/experimental_taintObjectReference). + +### Serializable arguments and return values {/*serializable-parameters-and-return-values*/} + +As client code calls the server action over the network, any arguments passed will need to be serializable. + +Here are supported types for server action arguments: + +* Primitives + * [string](https://developer.mozilla.org/en-US/docs/Glossary/String) + * [number](https://developer.mozilla.org/en-US/docs/Glossary/Number) + * [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) + * [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean) + * [undefined](https://developer.mozilla.org/en-US/docs/Glossary/Undefined) + * [null](https://developer.mozilla.org/en-US/docs/Glossary/Null) + * [symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), only symbols registered in the global Symbol registry via [`Symbol.for`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for) +* Iterables containing serializable values + * [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) + * [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) + * [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) + * [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) + * [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) and [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) +* [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) +* [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instances +* Plain [objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object): those created with [object initializers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer), with serializable properties +* Functions that are server actions +* [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) + +Notably, these are not supported: +* React elements, or [JSX](https://react.dev/learn/writing-markup-with-jsx) +* Functions, including component functions or any other function that is not a server action +* [Classes](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Classes_in_JavaScript) +* Objects that are instances of any class (other than the built-ins mentioned) or objects with [a null prototype](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects) +* Symbols not registered globally, ex. `Symbol('my new symbol')` + + +Supported serializable return values are the same as [serializable props](/reference/react/use-client#passing-props-from-server-to-client-components) for a boundary Client Component. + +## Utilisation {/*usage*/} + +### Server actions in forms {/*server-actions-in-forms*/} + +The most common use case of server actions will be calling server functions that mutate data. On the browser, the [HTML form element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) is the traditional approach for a user to submit a mutation. With React Server Components, React introduces first-class support for server actions in [forms](/reference/react-dom/components/form). + +Here is a form that allows a user to request a username. + +```js [[1, 3, "formData"]] +// App.js + +async function requestUsername(formData) { + 'use server'; + const username = formData.get('username'); + // ... +} + +export default App() { + + + + +} +``` + +In this example `requestUsername` is a server action passed to a `
`. When a user submits this form, there is a network request to the server function `requestUsername`. When calling a server action in a form, React will supply the form's [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) as the first argument to the server action. + +By passing a server action to the form `action`, React can [progressively enhance](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement) the form. This means that forms can be submitted before the JavaScript bundle is loaded. + +#### Handling return values in forms {/*handling-return-values*/} + +In the username request form, there might be the chance that a username is not available. `requestUsername` should tell us if it fails or not. + +To update the UI based on the result of a server action while supporting progressive enhancement, use [`useFormState`](/reference/react-dom/hooks/useFormState). + +```js +// requestUsername.js +'use server'; + +export default async function requestUsername(formData) { + const username = formData.get('username'); + if (canRequest(username)) { + // ... + return 'successful'; + } + return 'failed'; +} +``` + +```js {4,8}, [[2, 2, "'use client'"]] +// UsernameForm.js +'use client'; + +import {useFormState} from 'react-dom'; +import requestUsername from './requestUsername'; + +function UsernameForm() { + const [returnValue, action] = useFormState(requestUsername, 'n/a'); + + return ( + <> + + + +
+

Last submission request returned: {returnValue}

+ + ); +} +``` + +Note that like most Hooks, `useFormState` can only be called in [client code](/reference/react/use-client). + +### Calling a server action outside of `
` {/*calling-a-server-action-outside-of-form*/} + +Server actions are exposed server endpoints and can be called anywhere in client code. + +When using a server action outside of a [form](/reference/react-dom/components/form), call the server action in a [transition](/reference/react/useTransition), which allows you to display a loading indicator, show [optimistic state updates](/reference/react/useOptimistic), and handle unexpected errors. Forms will automatically wrap server actions in transitions. + +```js {9-12} +import incrementLike from './actions'; +import { useState, useTransition } from 'react'; + +function LikeButton() { + const [isPending, startTransition] = useTransition(); + const [likeCount, setLikeCount] = useState(0); + + const onClick = () => { + startTransition(async () => { + const currentCount = await incrementLike(); + setLikeCount(currentCount); + }); + }; + + return ( + <> +

Total Likes: {likeCount}

+ ; + + ); +} +``` + +```js +// actions.js +'use server'; + +let likeCount = 0; +export default async incrementLike() { + likeCount++; + return likeCount; +} +``` + +To read a server action return value, you'll need to `await` the promise returned. diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 6e6b58a45..8625ca4e8 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -6,9 +6,13 @@ "hasSectionHeader": true, "sectionHeader": "react@18.2.0" }, + { + "title": "Survol", + "path": "/reference/react" + }, { "title": "Hooks", - "path": "/reference/react", + "path": "/reference/react/hooks", "routes": [ { "title": "use",