Серверные острова

sitelo собирает статический HTML. Серверные острова заполняют то, что должно быть свежим, — часы, комментарии, наличие товара, всё, чему нужен запрос. Этот рецепт собирает страницу с островом времени, а затем запускает небольшой сервер на Node, который отдаёт dist/ и /_sitelo/islands.

Копия этого проекта лежит в репозитории sitelo, в examples/islands/.

Что вы получаете

Структура проекта

my-site/
  sitelo.config.js
  server.js              # хост на Node: статический dist + острова
  netlify.toml           # rewrite Netlify → функция
  vercel.json            # rewrite Vercel → api-маршрут
  package.json
  netlify/functions/
    islands.mjs          # обработчик островов для Netlify
  api/islands/
    [...path].js         # обработчик островов для Vercel
  src/
    index.ht.js          # страница с плейсхолдером острова
    js/
      islands.js         # клиентский загрузчик (собирается в dist/)
    islands/
      time.js            # серверный модуль-фрагмент
    css/
      styles.css
export default {
  site: 'https://example.com',
}

1. Модуль острова

Обычный файл .js (не .ht.js). Получает { name, props, request } и возвращает строку HTML. Этот использует время запроса и user-agent, чтобы было видно: он рендерится на каждый запрос.

export default function time({ props, request }) {
  const label = typeof props?.label === 'string' ? props.label : 'Время сервера'
  const now = new Date().toISOString()
  const ua = request?.headers?.get?.('user-agent') ?? 'unknown'

  return `
    <p><strong>${label}:</strong> <time datetime="${now}">${now}</time></p>
    <p class="muted">Отрендерено по запросу для <code>${escapeHtml(ua.slice(0, 48))}</code></p>
  `
}

function escapeHtml(value) {
  return value
    .replaceAll('&', '&amp;')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
    .replaceAll('"', '&quot;')
}

2. Разместите остров на странице

island() встраивает props в плейсхолдер. Сборка публикует запасной вариант; загрузчик заменяет его, когда эндпоинт ответит.

import { html, head, title, link, body, h1, p, script } from 'javascript-to-html'
import { island } from 'sitelo/islands'

export default () =>
  html({ lang: 'ru' },
    head(
      title('Демо серверных островов'),
      link({ rel: 'stylesheet', href: '/styles.css' }),
    ),
    body(
      h1('Статическая страница, живой остров'),
      p('Этот HTML собран один раз. Блок ниже заполняется в момент запроса.'),
      island(
        'time',
        { label: 'Прямо сейчас' },
        '<p>Загрузка времени сервера…</p>',
      ),
      script({ type: 'module', src: '/islands.js' }),
    ),
  )

3. Клиентский загрузчик

import { mountIslands } from 'sitelo/islands/client'

mountIslands()
body {
  font-family: system-ui, sans-serif;
  max-width: 36rem;
  margin: 2rem auto;
  padding: 0 1rem;
  line-height: 1.5;
}

[data-sitelo-island] {
  margin: 1.5rem 0;
  padding: 1rem 1.25rem;
  border: 1px solid #ccc;
}

[data-sitelo-island-state='loading'] {
  opacity: 0.7;
}

.muted {
  color: #666;
  font-size: 0.9rem;
}

4. Хост на Node

После sitelo build этот процесс отдаёт dist/ и рендерит острова через createIslandsNodeHandler из sitelo/islands/server. Модули островов остаются вне dist/ — хост импортирует их из src/.

import fs from 'node:fs'
import http from 'node:http'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { createIslandsFromDirectory, createIslandsNodeHandler } from 'sitelo/islands/server'

const root = path.dirname(fileURLToPath(import.meta.url))
const dist = path.join(root, 'dist')
const port = Number(process.env.PORT) || 3000

const handleIslands = createIslandsNodeHandler({
  islands: createIslandsFromDirectory(path.join(root, 'src/islands')),
})

const MIME = {
  '.html': 'text/html; charset=utf-8',
  '.js': 'text/javascript; charset=utf-8',
  '.css': 'text/css; charset=utf-8',
  '.svg': 'image/svg+xml',
  '.png': 'image/png',
  '.ico': 'image/x-icon',
  '.xml': 'application/xml',
  '.json': 'application/json',
}

function sendFile(res, filePath) {
  const ext = path.extname(filePath)
  res.statusCode = 200
  res.setHeader('Content-Type', MIME[ext] ?? 'application/octet-stream')
  fs.createReadStream(filePath).pipe(res)
}

function resolveStatic(urlPath) {
  const clean = decodeURIComponent(urlPath.split('?')[0])
  const relative = clean === '/' ? 'index.html' : clean.replace(/^\/+/, '')
  const candidate = path.normalize(path.join(dist, relative))

  if (!candidate.startsWith(dist + path.sep) && candidate !== dist) {
    return null
  }
  if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
    return candidate
  }

  const asIndex = path.join(candidate, 'index.html')
  if (fs.existsSync(asIndex) && fs.statSync(asIndex).isFile()) {
    return asIndex
  }

  return null
}

const server = http.createServer(async (req, res) => {
  await handleIslands(req, res, () => {
    const file = resolveStatic(req.url ?? '/')
    if (file) {
      sendFile(res, file)
      return
    }

    const notFound = path.join(dist, '404.html')
    res.statusCode = 404
    if (fs.existsSync(notFound)) {
      sendFile(res, notFound)
    } else {
      res.setHeader('Content-Type', 'text/plain; charset=utf-8')
      res.end('Не найдено')
    }
  })
})

server.listen(port, () => {
  console.log(`Слушаю на http://localhost:${port}`)
})

5. Сборка и запуск

npm install
sitelo build
node server.js

Откройте http://localhost:3000. Вы должны на мгновение увидеть запасной вариант, а затем время сервера. Обновите страницу — метка времени изменится. В sitelo (dev) и sitelo preview server.js не нужен: CLI уже отдаёт /_sitelo/islands.

Развёртывание

Этот пример поставляется с заготовками хостов рядом с сервером на Node:

Для serverless или edge в другом месте используйте createIslandsHandler (веб-Request → Response) — см. документацию по серверным островам. Направьте mountIslands({ endpoint }) на URL этой функции, если она не на том же источнике.

Заметки

Только статические хосты

У GitHub Pages, простого S3 и подобных хостов нет серверного процесса. Без эндпоинта островов запасной HTML просто остаётся на месте — страницы всё равно работают, только без живого фрагмента.

Держите props небольшими

Props путешествуют в HTML-атрибуте и в строке запроса. Не кладите туда секреты или крупные данные — получайте их внутри модуля острова, на сервере.

Документация по серверным островам · Базовый сайт / развёртывание · Все примеры