Адаптеры и пререндеринг

Команда написала приложение на SvelteKit и хочет задеплоить его. Один проект уходит на Vercel как serverless-функции, другой - на собственный сервер под Node, третий - это документация, которой хватит статического хостинга на CDN без всякого сервера. Один и тот же код SvelteKit обслуживает все три цели, но артефакт для каждой нужен свой. Эту трансформацию делает адаптер: маленький плагин сборки, который упаковывает приложение под конкретную платформу. Сменить цель деплоя - значит сменить одну строку адаптера, а не переписывать приложение.

• Документация и блог: adapter-static превращает сайт в набор файлов для GitHub Pages или CDN без сервера
• Корпоративный сервис на своём железе: adapter-node даёт обычный Node-сервер, запускаемый где угодно
• Стартап на Vercel: adapter-vercel упаковывает маршруты в serverless и edge функции под платформу
• Прототип без выбранной платформы: adapter-auto определяет окружение деплоя автоматически
• Лендинг с парой динамических форм: гибрид пререндеренных страниц и серверных action под node-адаптером

Предварительные знания

• Режимы рендеринга SvelteKit: SSR, CSR и опция prerender
• Понятие сборки фронтенд-приложения в артефакт для деплоя
• Базовое различие serverless-функций, постоянного Node-сервера и статического хостинга

Что делает адаптер

SvelteKit отделяет код приложения от деталей платформы, на которой оно запустится. Само приложение пишется одинаково, а превращением его в развёртываемый артефакт занимается адаптер - плагин, который выполняется в конце сборки. Один адаптер сделает набор статических файлов, другой - Node-сервер, третий - функции под облачную платформу. Адаптер указывают один раз в svelte.config.js.

Смысл такого разделения в переносимости. Перевод приложения с одной платформы на другую сводится к замене импорта адаптера и пересборке - код маршрутов, load и компонентов не меняется. Это позволяет начать на одной платформе и переехать на другую без переписывания приложения, что особенно ценно, пока окончательная цель деплоя ещё не выбрана.

Адаптер работает только на этапе сборки, а не в рантайме. Он анализирует маршруты, выполняет пререндер тех страниц, что помечены prerender, и формирует выходные файлы в нужном для платформы формате. Во время выполнения приложения адаптера уже нет - есть лишь созданный им артефакт.

static, node, vercel, auto

Официальные адаптеры покрывают основные сценарии деплоя. Каждый предполагает свою среду выполнения и свои возможности. Ключевое различие - может ли платформа исполнять серверный код в рантайме или отдаёт только заранее подготовленные файлы.

adapter-static требует, чтобы все маршруты можно было пререндерить: серверного рантайма у него нет, и страница с динамическими данными на запрос не соберётся. adapter-node даёт полноценный сервер, который держит SSR, form actions и +server.js эндпоинты в рантайме. adapter-vercel упаковывает то же самое в serverless и edge функции платформы. adapter-auto под капотом выбирает подходящий адаптер по обнаруженному окружению.

На adapter-static недоступно всё, что требует сервера в рантайме: form actions, +server.js эндпоинты и серверный handle. Если страница или раздел зависят от серверного исполнения на каждый запрос, статический адаптер для них не подойдёт - нужен node, vercel или другой серверный адаптер.

Выбор адаптера и пререндер под цель

Выбор адаптера определяется тем, что приложению реально нужно в рантайме. Если каждый маршрут можно построить заранее и серверная логика на запрос не требуется - подходит static, и весь сайт уходит на дешёвый CDN. Если нужны SSR, form actions или эндпоинты - берут серверный адаптер: node для своего сервера, vercel или аналог под выбранную облачную платформу.

Пререндер и адаптер - разные, но связанные настройки. prerender = true на странице говорит построить её HTML на сборке. Это работает с любым серверным адаптером: пререндеренные страницы отдаются как статика, а остальные рендерятся на сервере на запрос - получается гибрид. adapter-static же требует, чтобы пререндерилось всё приложение целиком, иначе сборка не пройдёт.

Разумная стратегия по умолчанию - оставить adapter-auto на старте, помечать заведомо статические страницы prerender = true, а зафиксировать конкретный адаптер тогда, когда платформа деплоя выбрана окончательно. Так приложение не привязывается к платформе раньше времени.

Связь с другими темами

Адаптеры - последний слой: они материализуют выбранный режим рендеринга под платформу:

• SSR, CSR и prerender — Адаптер реализует выбранный режим; static исключает SSR, node и vercel его поддерживают
• Гидрация — Пререндер и лёгкая гидрация вместе дают быстрый и отзывчивый результат на клиенте
• Hooks — Полностью статический адаптер не запускает серверный handle и эндпоинты во время выполнения

Итог

• Адаптер - плагин сборки, упаковывающий приложение SvelteKit под конкретную цель деплоя; задаётся в svelte.config.js
• adapter-static делает полностью статический сайт (все маршруты пререндерены), без серверного рантайма
• adapter-node собирает обычный Node-сервер с поддержкой SSR; adapter-vercel - serverless и edge функции под Vercel
• adapter-auto определяет поддерживаемую платформу деплоя автоматически и удобен как стартовый выбор
• prerender = true строит статический HTML на сборке для неизменных страниц; адаптер выбирают под то, что приложению реально нужно в рантайме

Связанные уроки

• sv-25-ssr-csr — Адаптер реализует выбранный режим рендеринга; без понимания SSR, CSR и prerender выбор адаптера беспредметен
• sv-26-hydration — Пререндер и лёгкая гидрация - две стороны одной цели: отдать пользователю готовое и быстрое
• sv-22-hooks — adapter-static исключает серверные функции, поэтому серверный handle и эндпоинты на нём недоступны