From c0bd72d2c71812eaf8b9bd81f84e55c05f51609b Mon Sep 17 00:00:00 2001 From: eps1lon Date: Mon, 12 Aug 2024 17:14:54 +0200 Subject: [PATCH 1/3] `react-markup` reference --- src/content/reference/react-markup/index.md | 16 +++++ .../reference/react-markup/renderToMarkup.md | 68 +++++++++++++++++++ src/sidebarReference.json | 14 +++- 3 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 src/content/reference/react-markup/index.md create mode 100644 src/content/reference/react-markup/renderToMarkup.md diff --git a/src/content/reference/react-markup/index.md b/src/content/reference/react-markup/index.md new file mode 100644 index 00000000000..2d897eb89c8 --- /dev/null +++ b/src/content/reference/react-markup/index.md @@ -0,0 +1,16 @@ +--- +title: React Markup APIs +--- + + + +The `react-markup` package provides the ability to render standalone HTML from Server Components for use in embedded contexts such as e-mails and RSS/Atom feeds. +It cannot use Client Components and does not hydrate. It is intended to be paired with the generic React package, which is shipped as `react` to npm. + + + +## APIs {/*apis*/} + +These APIs can be imported from the React Server environment (e.g. in Server Actions): + +* [`renderToMarkup`](/reference/react-markup/renderToMarkup) renders a non-interactive React tree with support for Server Components but not Client Components. \ No newline at end of file diff --git a/src/content/reference/react-markup/renderToMarkup.md b/src/content/reference/react-markup/renderToMarkup.md new file mode 100644 index 00000000000..0c73b644ae5 --- /dev/null +++ b/src/content/reference/react-markup/renderToMarkup.md @@ -0,0 +1,68 @@ +--- +title: renderToMarkup +--- + + + + +`renderToMarkup` renders a React tree to non-interactive HTML. + +```js +const stream = renderToMarkup(reactNode, options?) +``` + + + + + +--- + +## Reference {/*reference*/} + +### `renderToMarkup(reactNode, options?)` {/*renderToMarkup*/} + +You can call `renderToMarkup` in a React Server environment (e.g. in a Server Action) to render a non-interactive tree of React components to HTML. + +```js +import { renderToMarkup } from 'react-dom/server'; + +const markup = await renderToMarkup(); +``` + +#### Parameters {/*parameters*/} + +* `reactNode`: A React node you want to render to HTML. For example, a JSX element like ``. + +* **optional** `options`: An object for server render. + * **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/reference/react/useId) Useful to avoid conflicts when the markup is embedded in or combined with other markup that is rendered by React. + * **optional** `onError`: A callback that fires whenever there is a server error. By default, this only calls `console.error`. If you override it to [log crash reports,](#logging-crashes-on-the-server) make sure that you still call `console.error`. This is different to the rejection reason of the created Promise since it'll include the parent component stack. + * **optional** `signal`: An [abort signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that lets you [abort rendering](#aborting-server-rendering). The original Promise will reject. + +#### Returns {/*returns*/} + +`renderToMarkup` returns a Promise that will resolve with the HTML string of the rendered React tree. + +#### Caveats {/*caveats*/} + +* Will throw when Client Components (e.g. `useState` or `useEffect`) are used. + +--- + +## Usage {/*usage*/} + +### Rendering a React tree as an Email {/*rendering-a-react-tree-as-an-email*/} + +Await the call of `renderToMarkup` : + +```js {7} +import { renderToMarkup } from 'react-markup'; +import EmailTemplate from './my-email-template-component.js' + +async function action(email, name) { + "use server"; + // ... in your server, e.g. a Server Action... + const htmlString = await renderToMarkup(); + // ... send e-mail using some e-mail provider + await sendEmail({ to: email, contentType: 'text/html', body: htmlString }); +} +``` diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 50e0a3dffbd..f902a408826 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -390,6 +390,18 @@ } ] }, + { + "title": "react-markup", + "path": "/reference/react-markup", + "canary": true, + "routes": [ + { + "title": "renderToMarkup", + "path": "/reference/react-markup/renderToMarkup", + "canary": true + } + ] + }, { "hasSectionHeader": true, "sectionHeader": "Legacy APIs" @@ -433,4 +445,4 @@ ] } ] -} \ No newline at end of file +} From be631ebd808fd2bc6b3b3469cb75b2eefa1d2053 Mon Sep 17 00:00:00 2001 From: eps1lon Date: Wed, 14 Aug 2024 09:27:27 +0200 Subject: [PATCH 2/3] renderToMarkup -> renderToHTML --- src/content/reference/react-markup/index.md | 2 +- .../{renderToMarkup.md => renderToHTML.md} | 30 +++++++++++-------- src/sidebarReference.json | 4 +-- 3 files changed, 21 insertions(+), 15 deletions(-) rename src/content/reference/react-markup/{renderToMarkup.md => renderToHTML.md} (58%) diff --git a/src/content/reference/react-markup/index.md b/src/content/reference/react-markup/index.md index 2d897eb89c8..a8f435e97de 100644 --- a/src/content/reference/react-markup/index.md +++ b/src/content/reference/react-markup/index.md @@ -13,4 +13,4 @@ It cannot use Client Components and does not hydrate. It is intended to be paire These APIs can be imported from the React Server environment (e.g. in Server Actions): -* [`renderToMarkup`](/reference/react-markup/renderToMarkup) renders a non-interactive React tree with support for Server Components but not Client Components. \ No newline at end of file +* [`renderToHTML`](/reference/react-markup/renderToHTML) renders a non-interactive React tree with support for Server Components but not Client Components. \ No newline at end of file diff --git a/src/content/reference/react-markup/renderToMarkup.md b/src/content/reference/react-markup/renderToHTML.md similarity index 58% rename from src/content/reference/react-markup/renderToMarkup.md rename to src/content/reference/react-markup/renderToHTML.md index 0c73b644ae5..416fe77c644 100644 --- a/src/content/reference/react-markup/renderToMarkup.md +++ b/src/content/reference/react-markup/renderToHTML.md @@ -1,14 +1,15 @@ --- -title: renderToMarkup +title: renderToHTML +canary: true --- -`renderToMarkup` renders a React tree to non-interactive HTML. +`renderToHTML` renders a React tree to non-interactive HTML. ```js -const stream = renderToMarkup(reactNode, options?) +const stream = renderToHTML(reactNode, options?) ``` @@ -19,14 +20,19 @@ const stream = renderToMarkup(reactNode, options?) ## Reference {/*reference*/} -### `renderToMarkup(reactNode, options?)` {/*renderToMarkup*/} +### `renderToHTML(reactNode, options?)` {/*rendertohtml*/} -You can call `renderToMarkup` in a React Server environment (e.g. in a Server Action) to render a non-interactive tree of React components to HTML. +You can call `renderToHTML` to render a non-interactive tree of React components to HTML. +By default, it supports shared components and built-in components. +Server Components are only allowed if used in a React Server environment (e.g. in Server Actions). +You can also use it during Client-Side Rendering but only without Server Components. + +When a `` tag is rendered, `renderToHTML` will automatically add `` doctype. ```js -import { renderToMarkup } from 'react-dom/server'; +import { experimental_renderToHTML as renderToHTML } from 'react-dom/server'; -const markup = await renderToMarkup(); +const markup = await renderToHTML(); ``` #### Parameters {/*parameters*/} @@ -40,11 +46,11 @@ const markup = await renderToMarkup(); #### Returns {/*returns*/} -`renderToMarkup` returns a Promise that will resolve with the HTML string of the rendered React tree. +`renderToHTML` returns a Promise that will resolve with the HTML string of the rendered React tree. #### Caveats {/*caveats*/} -* Will throw when Client Components (e.g. `useState` or `useEffect`) are used. +* Will throw when Client APIs (e.g. `useState` or `useEffect`) are used. --- @@ -52,16 +58,16 @@ const markup = await renderToMarkup(); ### Rendering a React tree as an Email {/*rendering-a-react-tree-as-an-email*/} -Await the call of `renderToMarkup` : +Await the call of `renderToHTML` : ```js {7} -import { renderToMarkup } from 'react-markup'; +import { experimental_renderToHTML as renderToHTML } from 'react-markup'; import EmailTemplate from './my-email-template-component.js' async function action(email, name) { "use server"; // ... in your server, e.g. a Server Action... - const htmlString = await renderToMarkup(); + const htmlString = await renderToHTML(); // ... send e-mail using some e-mail provider await sendEmail({ to: email, contentType: 'text/html', body: htmlString }); } diff --git a/src/sidebarReference.json b/src/sidebarReference.json index f902a408826..7cbdb384f82 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -396,8 +396,8 @@ "canary": true, "routes": [ { - "title": "renderToMarkup", - "path": "/reference/react-markup/renderToMarkup", + "title": "renderToHTML", + "path": "/reference/react-markup/renderToHTML", "canary": true } ] From a3197e87794cbc1ab5add1940a4ec2e43b9abcf2 Mon Sep 17 00:00:00 2001 From: Strek Date: Wed, 14 Aug 2024 17:16:27 +0530 Subject: [PATCH 3/3] Update src/content/reference/react-markup/renderToHTML.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sébastien Lorber --- src/content/reference/react-markup/renderToHTML.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react-markup/renderToHTML.md b/src/content/reference/react-markup/renderToHTML.md index 416fe77c644..3d736028fe3 100644 --- a/src/content/reference/react-markup/renderToHTML.md +++ b/src/content/reference/react-markup/renderToHTML.md @@ -30,7 +30,7 @@ You can also use it during Client-Side Rendering but only without Server Compone When a `` tag is rendered, `renderToHTML` will automatically add `` doctype. ```js -import { experimental_renderToHTML as renderToHTML } from 'react-dom/server'; +import { experimental_renderToHTML as renderToHTML } from 'react-markup'; const markup = await renderToHTML(); ```