Update (2025-02-28): Because of the way I’m accessing the worker via Caddy and since blog is being routed via Cloudflare DNS/Cache, the Cache-Control headers returned by the worker seems to be getting ignored. I updated the Caddy section to hardcode a Cache-Control header for now, which seems to work but this could be done better.
OpenGraph protocol defines the og:image meta property which is used by apps like Bluesky, WhatsApp, Signal etc. to generate those nice cards whenever you paste a link. Some of my posts here have these already. Here’s what the HTML looks like for my recent article about spotify_player:
<meta property="og:image" content="https://blog.sangeeth.dev/posts/images/spotify-player-album-view.webp">
My Hugo theme does this automatically for every post as long as I have at least one image embedded in them. But for posts like the one you’re reading, I’m too lazy to make a preview image or find one and sometimes, there’s no such image. In these cases, I want to generate an image with a template that can serve as a nice link preview image.
Since I thought it might take too long to do this locally with Hugo (I tried, more at the end of this post) and I didn’t want to add another toolchain to my build process, I turned to hosting this online with a lightweight service. I thought Cloudflare Workers would be perfect for this thanks to their generous free tier.
Setting up the project #
I used Cloudflare’s wrangler CLI to setup the project:
pnpm create cloudflare@latest blog-og-image-service
I chose the following options in sequence:
- Hello World example
- Hello World Worker
- TypeScript
- Yes for version control
- No for deployment
I then went into blog-og-image-service directory and ran pnpm dev. This runs a local dev server at http://localhost:8787.
You define the logic when someone hits your endpoint inside the fetch function property of the default export inside src/index.ts:
export default {
async fetch(request, env, ctx): Promise<Response> {
return new Response('Hello World!');
},
} satisfies ExportedHandler<Env>;
Generating the image #
For the image generation, I wanted to use stuff I’m already familiar with—web technologies! I knew running Playwright/Puppeteer in workers might not be possible or even practical. After some research, I stumbled into @cloudflare/pages-plugin-vercel-og.
This uses @vercel/og, which only works in Vercel’s edge runtime but Cloudflare wraps over it and builds it such that its compatible inside both Cloudflare Pages and Workers. @vercel/og under the hood uses another Vercel project called Satori, which converts the markup into SVG and it is then converted into a PNG file by resvg.
Satori uses a version of Yoga layout engine by Meta, which is used by React Native to aid in building mobile app interfaces with JSX and CSS. If you’re familiar with React Native, you’d know this means we can only use Flexbox for layout and we have to use style properties for CSS.
Before we can write JSX, we need to make a few changes. First, rename src/index.ts to src/index.tsx. Next, update the tsconfig.json so that it also includes .tsx files:
{
"include": ["worker-configuration.d.ts", "src/**/*.ts", "src/**/*.tsx"]
}
Lastly, update wrangler.jsonc file to use src/index.tsx as the entrypoint:
{
"main": "src/index.tsx"
}
Here’s how you would render a 1200×630px image, which is the recommended size for an og:image, that says “Hello, world!” in white text on a gray background:
async fetch(request, env, ctx): Promise<Response> {
return new ImageResponse(
(
<div
style={{
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
width: '100vw',
height: '100vh',
backgroundColor: '#333',
color: '#fff',
}}
>
<div style={{ textAlign: 'center' }}>Hello, world!</div>
</div>
),
{
width: 1200,
height: 630,
}
);
}
One thing to note is that you almost have to do everything with just flex layout. Any time you add child elements, you have to ensure parent element has display: flex or otherwise, you’ll get a helpful error in the console.
You can use img tags to add pictures and they work as you’d expect. If you provide a remote URL to src, it will fetch and render the image. This is slow, so it’s better to encode as base64 and inline the images you want. I wanted to embed the Bluesky logo so I grabbed the SVG and embedded it as I’d usually in JSX files and it just worked.
We can also load and use different fonts. There is no method provided for this but Vercel docs has a loadGoogleFont function you can copy and pass into the options object as follows:
export default {
async fetch(request, env, ctx): Promise<Response> {
return new ImageResponse(
(
<div
style={{
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
width: '100vw',
height: '100vh',
backgroundColor: '#333',
color: '#fff',
fontSize: 'Lobster',
}}
>
<div style={{ textAlign: 'center' }}>Hello, world!</div>
</div>
),
{
width: 1200,
height: 630,
fonts: [
{
name: 'Lobster',
data: await loadGoogleFont('Lobster', 'Hello, world!'),
style: 'normal',
},
],
}
);
},
} satisfies ExportedHandler<Env>;
Emojis by default won’t render correctly. To enable support, pass emoji: "twemoji" to the options object.
I scrapped together the following for my own blog posts (excuse the piss-poor markup) which looks like this when rendered:
const texts = {
automagicHeader: 'Automagic',
postTitle: "My awesome new post",
username: '@runofthemillgeek.com',
section: "TIL",
};
const allTextsAsString = Object.values(texts).join('');
const cssVars = {
cardBackground: '#121212',
textColor: '#eee',
mutedTextColor: '#ccc',
headerColor: '#eee',
lineColor: '#333',
};
const sectionEl = section ? (
<div
style={{
alignSelf: 'center',
padding: '4px 16px',
border: `4px solid ${cssVars.textColor}`,
borderRadius: '9999px',
color: cssVars.textColor,
fontWeight: 700,
textTransform: 'uppercase',
fontFamily: 'Inter',
fontSize: 20,
}}
>
{section}
</div>
) : null;
return new ImageResponse(
(
<div
style={{
display: 'flex',
flexDirection: 'column',
alignItems: 'stretch',
justifyContent: 'center',
height: '100vh',
width: '100vw',
fontFamily: '"Inter"',
fontWeight: 400,
padding: '10px 25px',
color: cssVars.textColor,
background: cssVars.cardBackground,
}}
>
<div style={{ display: 'flex', flexDirection: 'column', flexBasis: "100px" }}>
<div data-spacer style={{ flex: '1 1 0', width: '1px', alignSelf: 'center', background: cssVars.lineColor }} />
<div style={{ display: 'flex', alignItems: 'center' }}>
<div data-line style={{ flex: '1 1 0', height: '1px', background: cssVars.lineColor }} />
<div
style={{
fontSize: 48,
fontWeight: 700,
padding: '0 10px',
lineHeight: 1,
color: cssVars.headerColor,
}}
>
{texts.automagicHeader}
</div>
<div data-line style={{ flex: '1 1 0', height: '1px', background: cssVars.lineColor }} />
</div>
</div>
<div style={{ flex: '1 1 0', display: 'flex', flexDirection: 'column', justifyContent: 'center' }}>
<div style={{ display: 'flex', justifyContent: 'center', marginTop: sectionEl ? 32 : 8 }}>{sectionEl}</div>
<div style={{ display: 'flex', justifyContent: 'center' }}>
<h1 style={{ fontSize: 66, fontWeight: 300, textAlign: 'center', color: '#fff' }}>{texts.postTitle}</h1>
</div>
</div>
<div
style={{
flexBasis: "100px",
display: 'flex',
justifyContent: 'center',
marginTop: '40px',
alignItems: 'center',
gap: '6px',
fontSize: 32,
}}
>
<img style={{ position: 'relative', top: '2px' }} src={bskyLogo} width={32} height={30} />
<div style={{ color: cssVars.mutedTextColor }}>{texts.username}</div>
</div>
</div>
),
{
width: 1200,
height: 630,
fonts: [
{
name: 'Inter',
data: await loadGoogleFont('Inter', allTextsAsString, 400),
weight: 400,
style: 'normal',
},
{
name: 'Inter',
data: await loadGoogleFont('Inter', allTextsAsString, 300),
weight: 300,
style: 'normal',
},
{
name: 'Inter',
data: await loadGoogleFont('Inter', allTextsAsString, 700),
weight: 800,
style: 'normal',
},
{
name: 'Inter',
data: await loadGoogleFont('Inter', allTextsAsString, 500),
weight: 500,
style: 'normal',
},
],
}
);
Note: You might want to parallelize those Google Fonts calls.
Deploying #
To deploy the project, run:
pnpm run deploy
If you’re using Wrangler for the first time, it’ll ask you to authenticate with your Cloudflare account in the browser. Follow the instructions printed in the CLI and the worker will be deployed if all goes well. By default, it uses the project name combined with the org name to generate a URL for the worker, blog-og-image-service.sangeeth.workers.dev in my case.
I’ve configured mine further to accept a url query param which is only valid for my blog posts. I also setup Caddy to proxy the requests at /api/og-image to the above service so that I don’t need to hardcode the Cloudflare URL for the worker. Here’s how the Caddy config looks like:
blog.sangeeth.dev {
# --- snip ---
handle /api/og-image* {
reverse_proxy https://blog-og-image-service.sangeeth.workers.dev {
header_up Host {upstream_hostport}
header_up Referer {http.request.header.Referer}
header_down Cache-Control "public, max-age=600"
}
}
# --- snip ---
}
This endpoint renders the og:image you are seeing for this article. You can try copying the link in the address bar and pasting it into your favorite chat app or social media app and see what comes up. If you’re lazy like me, you can click here instead.
Can’t we just use Hugo’s image functions? #
At first, I looked into using Hugo’s images.Filter function. I found an article by Aaro that gave me hints on how to go on about this. Sadly, this proved to be a bit too complicated and inflexible. I couldn’t find a nice and intuitive way to layout text and images while having some padding/gap around them. Any attempts to work around this by resizing rendered low quality images. I gave up after wasting a solid hour at this.