В данной статье рассказывается об автогенерации превью с помощью Satori.
Satori - библиотека от Vercel, которая создана для того чтобы превращать HTML-верстку в SVG картинки. С помощью данной библиотеки будем динамически генерировать Open Graph превью для страниц. Вперед под кат :)
Динамическая генерация превью
У каждого сайта есть специальные теги - Open Graph, они нужны для того чтобы поисковые системы оптимизировали выдачу контента в самом поиске. Также данные теги нужны для того чтобы при отправке ссылки мессенджеры могли подтянуть заголовок, описание и превью для сайта.
Тема OG несколько запутана, однако сейчас постараемся разложить все по полочкам. Open Graph-теги выглядят следующим образом:
🏀 Генерируем темплейт внутри API, конвертируем его, отдаем пользователю.
Генерация VDOM-темплейта
Как уже говорилось до этого - нам нужно сгенерировать темплейт с помощью satori-html. Сама генерация темплейта тоже делится на несколько частей:
Написать стилизацию;
Написать верстку;
Добавить данные, которые придут с API;
Сгенерировать темлейт.
Типизация
Сперва поговорим о типизации. В моем темплейте будет виден заголовок, подзаголовок, описание и url. Все это будет на фоне градиента, основной цвет которого будем передавать внутри параметра gradient.
Также нужна схема для того чтобы проверять пришли ли все параметры в GET-запросе. Будем делать это с помощью zod.
Теперь нужно сгенерировать сам темплейт. Будем делать это с помощью satori-html, который позволяет передать HTML-строку, на выходе получим VDOM, который совместим с satori.
Сам темплейт будем генерировать с помощью метода generatePreviewTemplate, который выглядит следующим образом:
Теперь нужно создать эндпоинт, который внутри будет генерировать темплейт, конвертировать его в svg, а затем и в png.
Для того чтобы создать API в Nuxt потребуется создать директорию server/api и добавить туда файл, имя которого и будет являть эндпоинтом, в моем случае это og.get.ts, который будет доступен по ссылке /api/og.
import satori, { FontWeight } from "satori";
import generatePreviewTemplate from "@d/previewTemplate";
import { getFontUrl } from "~/utils/fontPath";
import { OPEN_GRAPH_PREVIEW_SIZE } from "@/constants/openGraph";
import type { Fonts } from "@/types/fonts.types";
import { PreviewGradientColor, previewTemplateSchema } from "@/types/preview.types";
import { useSafeValidatedQuery } from "h3-zod";
import { Resvg } from "@resvg/resvg-js";
Импортируется satori и FontWeight. Первый нужен для того чтобы сгенерировать svg, второй для того чтобы указать жирность шрифта. Satori нужен хотя бы один шрифт для того чтобы зарендерить темплейт в svg;
generatePreviewTemplate нужен для того чтобы сгенерировать VDOM-дерево (темплейт), который будет рендерить Satori;
getFontUrl нужен для того чтобы достать полный путь к шрифту;
OPEN_GRAPH_PREVIEW_SIZE - константа с размером для картинки превью. Золотой стандарт - 1200px x 630px;
Fonts - типизация для шрифтов. Ее можно посмотреть вот тут;
PreviewGradientColor и previewTemplateSchema нужны для того чтобы типизировать наши параметры у GET-запроса;
useSafeValidatedQuery используется для того чтобы проверить пришли ли все параметры в GET-запросе, исходя из zod-схемы;
Resvg - библиотека для конвертации из svg в png.
Интерфейс для шрифтов
Также создаем свой интерфейс для шрифтов, для того чтобы их было удобнее писать, типизируя новый объект:
Далее обрабатываем наш GET-запрос и выцепляем параметры. Если некоторые обязательные параметры отсутствуют - то useSafeValidatedQuery вернет {success: false, error: Error}.
// Validation of GET query
const query = await useSafeValidatedQuery(event, previewTemplateSchema);
if (!query.success) {
return "400! Bad Request :(";
}
Генерация темплейта
Теперь нужно сгенерировать темплейт, делаем это исходя из наших GET-параметров:
Можно заметить тут функции decodeURIComponent - они используются для того чтобы декодировать данные из GET-параметров. Чуть дальше (когда будем писать composable) увидим почему их приходится декодировать.
Генерация svg и png
Теперь дело за малым - сгенерировать svg, конвертировать в png и отдать пользователю:
Теперь нужно сделать так, чтобы страницы в Nuxt динамически встраивали в себя Open Graph мета-теги, которые мы укажем. Будем делать это с помощью composable.
Внизу предоставлен полный листинг нашего composable:
import type { PreviewTemplate } from "@/types/preview.types";
import { OPEN_GRAPH_PREVIEW_SIZE } from "~/constants/openGraph";
/**
* Utility for generation OG Preview URL
* @param rootUrl URL of the site
* @param params Preview parameters
* @returns URL
*/
const generatePreviewURL = (rootUrl: string, params: PreviewTemplate): string => {
const title = encodeURIComponent(params.title);
const description = encodeURIComponent(params.description);
const url = encodeURIComponent(params.url);
const queryParams = new URLSearchParams({
title,
description,
url,
});
if (params.subtitle) {
queryParams.append(
"subtitle",
encodeURIComponent(params.subtitle)
);
}
if (params.gradient) {
queryParams.append("gradient", params.gradient);
}
return `${rootUrl}/api/og?${queryParams.toString()}`;
};
/**
* Include Open Graph meta tags (and twitter too🐦) into page head tag
* @param title Title of the page
* @param subtitle Subtitle of the page
* @param description Description of the page
* @param gradient Gradient to use
*/
export const useOpenGraph = async ({ description, gradient, title, subtitle }: Omit<PreviewTemplate, "url">) => {
const route = useRoute();
const config = useRuntimeConfig();
const url = `"${config.public.URL}${route.path}"`;
debugDo(() => {
console.groupCollapsed("useOpenGraph.ts: Preview of generated API URL");
console.log("URL", generatePreviewURL(config.public.URL, { description, url, title, gradient, subtitle }));
console.groupEnd();
});
const previewSizeMeta = Object.keys(OPEN_GRAPH_PREVIEW_SIZE).map(key => {
return {
property: `og:image:${key}`,
content: OPEN_GRAPH_PREVIEW_SIZE[
key as keyof typeof OPEN_GRAPH_PREVIEW_SIZE
].toString()
};
});
const previewURL = generatePreviewURL(config.public.URL, { description, gradient, title, subtitle, url });
useHead({
meta: [
// Twitter OG
{
property: "twitter:card",
content: "summary_large_image",
},
{
property: "twitter:image",
content: previewURL
},
// Basic OG
{
property: "og:description",
content: description,
},
{
property: "og:title",
content: title,
},
{
property: "og:image",
content: previewURL
},
...previewSizeMeta,
]
});
};
Генерирование URL'а для Open Graph Image
Нужно сгенерировать ссылку, которая будет вести на эндпоинт нашего API, причем нужно сделать это так, чтобы в URL'е были все необходимые GET-параметры. Этим занимается функция generatePreviewURL:
/**
* Utility for generation OG Preview URL
* @param rootUrl URL of the site
* @param params Preview parameters
* @returns URL
*/
const generatePreviewURL = (rootUrl: string, params: PreviewTemplate): string => {
const title = encodeURIComponent(params.title);
const description = encodeURIComponent(params.description);
const url = encodeURIComponent(params.url);
const queryParams = new URLSearchParams({
title,
description,
url,
});
if (params.subtitle) {
queryParams.append(
"subtitle",
encodeURIComponent(params.subtitle)
);
}
if (params.gradient) {
queryParams.append("gradient", params.gradient);
}
return `${rootUrl}/api/og?${queryParams.toString()}`;
};
Можем увидеть что тут мы используем функцию encodeURIComponent, которая инкапсулирует все пробелы и спец. символы которые не могут находиться в URL'е. Именно поэтому ранее производился декодинг параметров с помощью decodeURIComponent.
Проверка ссылки
В самом начале нашего composable мы проводим проверку корректно ли сгенерировался URL. debugDo - утилита, которая вызывает переданный коллбэк в случае, если process.dev === true:
/**
* Include Open Graph meta tags (and twitter too🐦) into page head tag
* @param title Title of the page
* @param subtitle Subtitle of the page
* @param description Description of the page
* @param gradient Gradient to use
*/
export const useOpenGraph = async ({ description, gradient, title, subtitle }: Omit<PreviewTemplate, "url">) => {
const route = useRoute();
const config = useRuntimeConfig();
const url = `"${config.public.URL}${route.path}"`;
debugDo(() => {
console.groupCollapsed("useOpenGraph.ts: Preview of generated API URL");
console.log("URL", generatePreviewURL(config.public.URL, {description, url, title, gradient, subtitle}));
console.groupEnd();
});
// ...
}
Генерация тегов для размерности картинки
В Open Graph существует два специальных мета-тега для указания картинки для превью, у этих тегов следующие property:
og:image:width;
og:image:height.
В данном листинге с помощью функционального выражения генерируем данные мета-теги:
// OPEN_GRAPH_PREVIEW_SIZE был импортирован и имеет следующие поля:
// export const OPEN_GRAPH_PREVIEW_SIZE = {
// width: 1200,
// height: 630
// };
const previewSizeMeta = Object.keys(OPEN_GRAPH_PREVIEW_SIZE).map(key => {
return {
property: `og:image:${key}`,
content: OPEN_GRAPH_PREVIEW_SIZE[
key as keyof typeof OPEN_GRAPH_PREVIEW_SIZE
].toString()
};
});
Использование мета-тегов
Теперь нам осталось просто использовать другой composable - useHead, который вставляет перечисленные теги в <head>.
Стоит упомянуть, что useHead доступен только в Nuxt, но в других SSR-фреймворках есть его аналоги.
