Escrever páginas

Qualquer ficheiro terminado numa extensão de página é uma página. Extensões por omissão: .ht.js, .html.js, e as variantes TypeScript / JSX (.ht.ts, .ht.tsx, …).

Se a saída começar por <html>, o sitelo acrescenta <!DOCTYPE html> automaticamente. Para a marcação recomendamos o ht.js (javascript-to-html): funções de etiqueta que devolvem strings, sem motor de templates nem runtime do React.

1. Uma função que devolve HTML

export default ({ params, data, dev }) => `
  <html>
    <body><h1>Olá</h1></body>
  </html>
`

import { html, body, h1 } from 'javascript-to-html'

export default ({ params, data, dev }) =>
  html(
    body(h1('Olá'))
  )

export default function Page({ params, data, dev }) {
  return (
    <html>
      <body><h1>Olá</h1></body>
    </html>
  )
}

Os ficheiros JSX usam *.ht.jsx / *.ht.tsx e precisam de react e react-dom instalados. Vê as limitações de JSX mais abaixo — o sitelo transforma JSX em HTML estático na compilação; não é uma aplicação React no navegador.

2. Uma simples string

export default `<html><body><h1>Mais estático que isto, impossível</h1></body></html>`

3. Um módulo estruturado

Mantém render, data e generateStaticParams juntos:

export default {
  generateStaticParams: () => [{ slug: 'hello' }],
  data: ({ params }) => ({ title: params.slug }),
  render: ({ data }) => `<html><body><h1>${data.title}</h1></body></html>`,
}

import { html, body, h1 } from 'javascript-to-html'

export default {
  generateStaticParams: () => [{ slug: 'hello' }],
  data: ({ params }) => ({ title: params.slug }),
  render: ({ data }) =>
    html(
      body(h1(data.title))
    ),
}

export default {
  generateStaticParams: () => [{ slug: 'hello' }],
  data: ({ params }) => ({ title: params.slug }),
  render: ({ data }) => (
    <html>
      <body><h1>{data.title}</h1></body>
    </html>
  ),
}

Limitações de JSX

O sitelo consegue renderizar páginas .ht.jsx / .ht.tsx com react-dom/server, para poderes escrever com a sintaxe JSX habitual. Isso é uma comodidade de escrita — não uma aplicação React.

O React foi feito para o navegador: uma árvore de componentes que monta, hidrata e responde a eventos. O sitelo nunca envia esse runtime com as tuas páginas. Na compilação renderiza o teu JSX para uma string HTML, escreve o ficheiro e fica por aí. Não há bundle do React no cliente, nem hidratação, nem DOM virtual à espera no navegador.

Por isso:

Os handlers de eventos (onClick, onChange, …) não fazem nada no site final — não há ninguém à escuta. O servidor de desenvolvimento avisa se os encontrar.
Os hooks (useState, useEffect, …) não fazem parte da página publicada. Podem correr uma vez durante a renderização da compilação; não guardam estado no navegador.
As APIs exclusivas do navegador (window, document) não estão disponíveis enquanto a página é renderizada na compilação.
dangerouslySetInnerHTML serve para injetar strings de HTML; a interatividade continua a precisar de um <script> de cliente à parte.

Para cliques, formulários e outro comportamento de cliente, liga um script normal através do pipeline de recursos, ou usa ilhas de servidor para HTML gerado no momento do pedido. Quando não precisares da sintaxe JSX, prefere o ht.js ou templates de string — sem instalar o React, e com um modelo que encaixa em «HTML na compilação».

Contexto de renderização

Cada função de página recebe um único argumento:

params

Os parâmetros de rota desta página (Record<string, string | string[]>).

data

O que a tua função data() devolveu.

page

Metadados da rota (routePath, relativePath, …).

dev

true no servidor de desenvolvimento, false na compilação.