vercel/og

@vercel/og Pages Plugin は、Web ページのソーシャル画像を描画するミドルウェアです。任意の画像を作る API も含まれます。

名前のとおり、@vercel/og ↗ を使います。この Plugin と基盤の Satori ↗ ライブラリは、Vercel チームが作成しました。

@vercel/og Pages Plugin をインストールするには、次を実行します。

npm i @cloudflare/pages-plugin-vercel-og

yarn add @cloudflare/pages-plugin-vercel-og

pnpm add @cloudflare/pages-plugin-vercel-og

bun add @cloudflare/pages-plugin-vercel-og

import React from "react";
import vercelOGPagesPlugin from "@cloudflare/pages-plugin-vercel-og";

interface Props {
	ogTitle: string;
}

export const onRequest = vercelOGPagesPlugin<Props>({
	imagePathSuffix: "/social-image.png",
	component: ({ ogTitle, pathname }) => {
		return <div style={{ display: "flex" }}>{ogTitle}</div>;
	},
	extractors: {
		on: {
			'meta[property="og:title"]': (props) => ({
				element(element) {
					props.ogTitle = element.getAttribute("content");
				},
			}),
		},
	},
	autoInject: {
		openGraph: true,
	},
});

Plugin は 6 つのプロパティを持つオブジェクトを受け取ります。

• imagePathSuffix: 生成した画像を公開するパスのサフィックスです。たとえば、この Plugin を functions/blog/_middleware.ts にマウントし、imagePathSuffix を /social-image.png に設定し、/blog/hello-world ページがある場合、画像は /blog/hello-world/social-image.png で利用できます。

• component: 画像の描画に使う React コンポーネントです。デフォルトでは、対象 Web ページのパス名（例: /blog/hello-world）と同じ pathname プロパティが渡されます。extractors オプションで、より動的なプロパティも渡せます。

• extractors: 省略可能なオブジェクトで、省略可能なプロパティが 2 つあります。on と onDocument です。それぞれ、オブジェクトを受け取り、HTMLRewriter の要素ハンドラー または ドキュメントハンドラー を返す関数を設定できます。オブジェクト引数を書き換えると、React コンポーネントに追加のプロパティを渡せます。上の例では、要素ハンドラーで Web ページから og:title メタタグを取り出し、ogTitle プロパティとして React コンポーネントへ渡します。対象 Web ページの値を使う動的画像を作るときの主な仕組みです。

• options: @vercel/og ライブラリへそのまま渡す、省略可能なオブジェクト ↗ です。

• onError: Response、または Response の Promise を返す省略可能な関数です。imagePathSuffix へのリクエストがあり、extractors が指定されているのに、対象 Web ページが有効な HTML でないときに呼ばれます。デフォルトは 404 レスポンスです。

• autoInject: 省略可能なオブジェクトで、省略可能なプロパティ openGraph があります。true にすると、Plugin は対象 Web ページに og:image、og:image:height、og:image:width メタタグを自動で設定します。

この Plugin の API を使って、ミドルウェアとしてだけでなく、任意の画像も生成できます。

たとえば、次のコードは "Hello, world!" と書かれた画像を生成し、/greet で利用できます。

import React from "react";
import { ImageResponse } from "@cloudflare/pages-plugin-vercel-og/api";

export const onRequest: PagesFunction = async () => {
  return new ImageResponse(
    <div style={{ display: "flex" }}>Hello, world!</div>,
    {
      width: 1200,
      height: 630,
    }
  );
};

これは、基盤の @vercel/og ライブラリ ↗ が提供する API と同じです。