renderToString

const html = renderToString(reactNode, options?)

• Referência
  • renderToString(reactNode, options?)
• Usage
  • Renderizando uma árvore React como HTML para uma string
• Alternativas
  • Migrando de renderToString para uma renderização de streaming no servidor
  • Migrando de renderToString para uma pré-renderização estática no servidor
  • Removendo renderToString do código do cliente
• Solução de problemas
  • Quando um componente suspende, o HTML sempre contém um fallback

Referência

renderToString(reactNode, options?)

No servidor, chame renderToString para renderizar seu app para HTML.

import { renderToString } from 'react-dom/server';

const html = renderToString(<App />);

No cliente, chame hydrateRoot para tornar o HTML gerado pelo servidor interativo.

Veja mais exemplos abaixo.

Parâmetros

• reactNode: Um nó React que você quer renderizar para HTML. Por exemplo, um nó JSX como <App />.

• opcional options: Um objeto para renderização no servidor.

  • opcional identifierPrefix: Um prefixo de string que o React usa para IDs gerados por useId. Útil para evitar conflitos ao usar múltiplos roots na mesma página. Deve ser o mesmo prefixo passado para hydrateRoot.

Retornos

Uma string HTML.

Ressalvas

• renderToString tem suporte limitado para Suspense. Se um componente suspender, renderToString imediatamente envia seu fallback como HTML.

• renderToString funciona no navegador, mas usá-lo no código do cliente não é recomendado.

Usage

Renderizando uma árvore React como HTML para uma string

Chame renderToString para renderizar seu app para uma string HTML que você pode enviar com a resposta do seu servidor:

import { renderToString } from 'react-dom/server';

// A sintaxe do manipulador de rota depende da sua framework de backend
app.use('/', (request, response) => {
  const html = renderToString(<App />);
  response.send(html);
});

Isso produzirá a saída HTML inicial não interativa dos seus componentes React. No cliente, você precisará chamar hydrateRoot para hidratar o HTML gerado pelo servidor e torná-lo interativo.

Alternativas

Migrando de renderToString para uma renderização de streaming no servidor

renderToString retorna uma string imediatamente, logo não suporta streaming de conteúdo conforme ele carrega.

Quando possível, recomendamos o uso destas alternativas com todos os recursos:

• Se você usa Node.js, use renderToPipeableStream.
• Se você usa Deno ou um tempo de execução de borda moderno com Web Streams, use renderToReadableStream.

Você pode continuar usando renderToString se seu ambiente de servidor não suporta streams.

Migrando de renderToString para uma pré-renderização estática no servidor

renderToString retorna uma string imediatamente, logo não suporta esperar pelos dados carregarem para a geração HTML estática.

Recomendamos usar essas alternativas com todos as funcionalidades:

• Se você usa Node.js, use prerenderToNodeStream.
• Se você usar Deno ou um tempo de execução de borda moderno com Web Streams, use prerender.

Você pode continuar usando renderToString se seu ambiente de geração de site estático não suporta streams.

Removendo renderToString do código do cliente

Às vezes, renderToString é usado no cliente para converter algum componente para HTML.

// 🚩 Desnecessário: usando renderToString no cliente
import { renderToString } from 'react-dom/server';

const html = renderToString(<MyIcon />);
console.log(html); // Por exemplo, "<svg>...</svg>"

Importar react-dom/server no cliente aumenta desnecessariamente o tamanho do seu bundle e deve ser evitado. Se você precisa renderizar algum componente para HTML no navegador, use createRoot e leia HTML do DOM:

import { createRoot } from 'react-dom/client';
import { flushSync } from 'react-dom';

const div = document.createElement('div');
const root = createRoot(div);
flushSync(() => {
  root.render(<MyIcon />);
});
console.log(div.innerHTML); // Por exemplo, "<svg>...</svg>"

A chamada flushSync é necessária para que o DOM seja atualizado antes de ler sua propriedade innerHTML.

Solução de problemas

Quando um componente suspende, o HTML sempre contém um fallback

renderToString não suporta totalmente Suspense.

Se algum componente suspender (por exemplo, porque é definido com lazy ou busca dados), renderToString não esperará que seu conteúdo seja resolvido. Em vez disso, renderToString encontrará o limite <Suspense> mais próximo acima dele e renderá sua prop fallback no HTML. O conteúdo não aparecerá até que o código do cliente carregue.

Para resolver isso, use uma das soluções de streaming recomendadas. Para renderização no lado do servidor, elas podem fazer streaming do conteúdo em pedaços à medida que ele é resolvido no servidor, de modo que o usuário veja a página sendo progressivamente preenchida antes que o código do cliente carregue. Para a geração de site estático, elas podem esperar que todo o conteúdo seja resolvido antes de gerar o HTML estático.