Repository navigation
Conversation
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
fe5c802 to
c0c254c
Compare
| ## Worker size | ||
|
|
||
| On Cloudflare, importing `void/og` adds Takumi's WebAssembly renderer to your Worker: about 4.3 MB, or 1.9 MB compressed. Cloudflare limits a Worker to 3 MB compressed on Workers Free and 10 MB on Workers Paid (see [Worker size](https://developers.cloudflare.com/workers/platform/limits/#worker-size)), so on Workers Free the rest of your app has about 1.1 MB. Apps that do not import `void/og` do not include the renderer. |
There was a problem hiding this comment.
Cloudflare changed these limits on September 4, 2026: the 3 MB (Free) and 10 MB (Paid) check on the compressed bundle was removed, and Workers Free and Workers Paid now both allow 64 MiB, measured uncompressed (changelog, Worker size). The limits page now says: “There is no compressed size limit. Only the uncompressed bundle size counts.”
So void/og adds about 4 MiB, which fits on either plan with plenty of room.
There was a problem hiding this comment.
Thanks for the tip. I forgot about that and am glad they're much higher now. I'm glad the size concern is gone. Will update it!
There was a problem hiding this comment.
@ogawa0071 Thanks for the PR! I've pushed some follow-up commits on top of yours. Summary below, please have a look and lemme know if there's anything amiss.
At the bottom there are notes for reviewers (cc @cpojer):
Changes since the original submission
API
ImageResponseOptionsis now Void's own list, mapped to Takumi's options one by one:width,height,debug,fonts,fallbackFonts,emoji,lang,images(allowUrl,maxBytes,timeout,throwOnError), plusstatus,statusTextandheaders. Takumi's other options (format,devicePixelRatio,css,renderer,module,fontFamilies, …) are no longer accepted, so a Takumi upgrade can't change Void's API, and backend options can't bypass the per-image font handling.- A
fontsentry is a font file's URL or{ name, data, weight?, style?, lang? }.weightaccepts any value from 1 to 1000; leaving it out lets a variable font follow each element'sfontWeight(e.g.550). - New
fallbackFonts: falseturns off the Google Fonts downloads, for apps that pass their own fonts. Cache-Controlis alwayspublic, max-age=0, must-revalidate. The dev-onlyno-cache, no-storewas dropped: withmax-age=0and no validator, clients refetch anyway.
Fallback fonts
- Fonts are requested from Google Fonts with
text=and only the characters in the image, so Google returns one small file. On a deployed Worker, a 45-character Japanese title went from 21 requests / 480 KB to 2 requests / 26 KB. Text too long for one request falls back to the per-range files. - An explicit
langnow chooses the Chinese, Japanese or Korean style before kana or Hangul in the text, so a Traditional Chinese title with a katakana word stays Chinese. ・andーare drawn with the Japanese family rather than a separate request.- Han text next to Hangul is drawn: both scripts went to Noto Sans KR, and the Hangul request replaced the Han one, so mixed Chinese/Japanese/Korean text drew boxes.
- Variable families are requested with their full weight range, so
fontWeight: 700draws real bold rather than a thickened 400. - When one fallback file fails to download, only that file is dropped; the others still render.
- Font handling moved into
packages/void/src/runtime/og-fonts.ts.
Dependencies and build
- Upgraded to
takumi-js~2.20.0, which fixes 2.19.0's fallback regression ("Łódź" next to Japanese drew as boxes). 2.20.0 renders pixel-identical to 2.18.2 on both backends. - The Node.js build check finds void's
package.jsonwithout assuming the module's depth.
Docs
- The guide describes
void/ogon its own, with no comparisons to or migration from other libraries. - New "Control font downloads" section: memory growth on long-running Node.js, Bun and Deno servers, subrequests and first-render latency on Workers, and
fallbackFonts: falsewith the app's own fonts. - The Fonts section says your fonts come before Geist and names Noto as the fallback. The font example uses a Google Fonts URL.
- The Worker size section states the renderer's cost (about 4.3 MB, 1.9 MB compressed).
- Shorter
void/ognotes inpackages/void/AGENTS.md.
Tests: 34 unit tests and 6 integration tests, covering the cases above.
Live demo with Latin, Japanese, Chinese, Korean, per-lang Han and weight cards: https://void-og-test.yangshun.workers.dev
Reviewer notes
- CPU time on Workers Free. A simple card takes ~10 ms of CPU, richer ones 30–80 ms, and the first render in a new isolate >100 ms, against Free's 10 ms per request. The guide tells Free users to cache image routes with
routing.revalidate. These numbers are from Miniflare; CPU time on a deployed Worker hasn't been measured. - Downloads while rendering. By default, text Geist can't draw fetches a font from Google Fonts, and emoji come from jsDelivr. Each download counts as a subrequest and slows the first render; a failed font draws boxes rather than failing the image.
fallbackFonts: falseopts out. Google'stext=parameter has no documented length limit; Void falls back to the per-range files above 6,000 encoded characters, below where it was measured to stop working. - Memory on Node.js, Bun and Deno. Each new title keeps ~37 KB of font data until restart, unbounded. Takumi's
render()uses a default renderer withoutfontCacheMaxBytes. A follow-up could create Void's own renderer with a cap. Documented for now. takumi-jsinstall on Node.js targets. Apps must listtakumi-jsindependencies, because the native addon can't be bundled and the production install fetches the right binary for the server. Rendering with the Wasm build on Node.js instead was measured at 2.5–3× slower with ~70 MB more memory. Raising Void's~2.20.0range later will ask Node.js apps to update theirs (the build error names the command). I couldn't find a better way around this. I think this is fine for now and we can revisit this.- Remote images. Markup can fetch remote images. Apps that put request values in image URLs should set
images.allowUrlandmaxBytes. Worth a security look. - Known Takumi behaviors, documented or noted rather than worked around:
- One Chinese style applies per image, chosen by
lang. - Geist is built into Takumi and stays as the last fallback.
- An element whose
font-familynames a font the image didn't pass can draw with it if an earlier image on the same server registered it. Plain text withoutfont-familyisn't affected.
- One Chinese style applies per image, chosen by
- API narrowed from the original. The original passed Takumi's options through, including other output formats (JPEG, WebP, ICO). Those are gone. Happy to discuss if any were important.
|
@kossnocorp could you review this PR and merge it when it's ready? |
|
@cpojer on it |
d25c3db to
785fbcc
Compare
|
@yangshun @ogawa0071 heads up, I updated the branch via GitHub, and it force-pushed the branch 🫠 Forgot it does that. Be careful if want to pull. |
|
@kossnocorp No problem, I won't be pushing anything for now. You can make any changes you want. |
785fbcc to
1876160
Compare
kossnocorp
left a comment
There was a problem hiding this comment.
Only critical issue is accepting HTML string.
I would still rename the module to void/image, but I'm not sure how to handle default image sizes. I would remove them in this PR and add OgImageResponse (imported from void/og) with presets like: "standard" | "x-large" | "x-small" | "linkedin".
Using xxHash would be a bit faster that SHA but I don't think it matters.
|
...and I would definitely use Inter instead of Geist. |
|
I haven't spent time looking at the API yet, but I see two issues in the implementation:
|
d291614 to
6dba994
Compare
|
@cpojer you were right regarding Takumi munching memory:
One can load multiple fonts into single family and eat as much memory as they want. I had to implement custom cache 🫠 |
Thanks for the suggestion! I agree that generating images from JSX isn’t really specific to Open Graph, and I can see why grouping it under void/image is appealing. Still, I’d prefer to keep void/og. The main goal of this module is to make moving from Next.js easy, and that works best when the differences are as small as possible. With the same module name and the same ImageResponse API, the JSX and options carry over unchanged, and only the import changes. The next/image counterpart is already in a separate PR (#450), so keeping this one as void/og also keeps the two apart, as Next.js does with next/og and next/image. For the default size, I’d suggest the same approach: keep only next/og’s 1200 × 630 default and let width and height cover everything else. One concern with presets named after networks like linkedin is that their recommended image sizes change often, so the presets would need updating to stay accurate, while width and height already handle any size. That said, I’m happy to go with whatever you think fits Void best. |
|
@kossnocorp Was cc @kane50613 for input. |
|
@yangshun the cache problem was in the eviction approach. It is family-based, but a family can contain any number of fonts. Here's the result after a fix:
|
|
Thanks for the explanation. Maybe it's a feature request we can raise to Takumi |
|
@yangshun I understand the compatibility concern, but I think we have consensus with @cpojer here, Re PR to Takumi, that would probably be a nice thing to do, but I can't promise I'll get to it. @ALL The PR is ready for a new round. I changed a lot of stuff:
I don't think we really have to publish it as I also tested Cloudflare's Kitesurf browser and Cloudflare Browser Run as additional renderers. We might consider adding them in the future and making the worker builds lighter, but it turned out Takumi is much faster ~50ms vs Browser Run ~500ms and Kitesurf 1000+ms. So they don't solve the immediate problem and add another. I would consider having Browser Run as the default renderer for Similarly for Cloudflare-based deployments we can replace |
Sounds good!
In my updates I constrained the API to be the minimum we need (aligning with @kossnocorp Thanks for the good work! |
Thanks for taking effort to bring Takumi into Void and reporting, I'm traveling right now will check on that ASAP |
|
@kossnocorp Thanks for the good work! |
Keep what maintainers act on: the declared options, the Node.js, Bun and Deno install check, and the Takumi upgrade steps. The font and Wasm details already live in the source comments. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Cloudflare now limits a Worker to 64 MiB uncompressed on every plan and has no compressed limit, so the guide no longer counts down from 3 MB. It keeps what the renderer costs: 4.3 MB more to upload and to start. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Text with Hangul draws Han characters with Noto Sans KR, so both scripts asked for the same family, and the Hangul request replaced the Han one. "日本語・中文・한국어" drew its Han characters, and the numbers beside them, as boxes. Ask the family for both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ings via void/html
…ilies leaking, improve fonts caching
cpojer
left a comment
There was a problem hiding this comment.
This is awesome, I'm excited about shipping this!
There are a few more issues:
- Node crash: When you have an unread image response, it can crash Node.js with an unhandled rejection. Try by constructing an ImageResponse from an async html template, cancel its body and let the template reject.
- Module loading: This PR overwrites how
@void/imageis loaded, so if in the future there is a dependency that uses@void/imagethat's different from the one in the app, you might get the wrong one. We should probably not mess with that. - React components:
renderImage(<Card />)works when Card is written as a function, but breaks with React class components. We should make class components work since the types say they are working. - Fonts: .woff appears to work in Takumi (and is listed in the docs), but the renderer in Void does not support it. .woff2 appears to work.
- Caching: It seems that this PR sets a one-minute caching header in development for SVG's even if
@void/imageis not used. We should only do this for generated images.
Please also update the package.json version to 1.10.0 (current released Void version).
In order to minimize WASM size woff is turned off on wasm builds and only enabled for node (napi) builds FYI I'm work on new unified caching module to allow more flexibility and address questions in this discussion thread I'd love to answer more questions if needed |
|
Yup that's fine, but then we should throw and not say in the docs that we support it. |
I guess this is a bug in upstream Takumi, will take a look and fix in next release if needed |
Update: kane50613/takumi#2596 fixed it |
2617102 to
3876cc5
Compare


Closes #442
Summary
Adds
void/og: anImageResponsethat renders JSX or an HTML string to a PNG from a route handler, for Open Graph and social preview images, on Cloudflare Workers and on the Node.js, Bun and Deno targets.Options
ImageResponseOptionsis Void's own list, mapped to Takumi's render options one by one, so a Takumi upgrade does not change the API:width,height,debug,fonts,emoji(twemoji,blobmoji,noto,openmoji,fluent,fluentFlat),status,statusText,headers.lang: chooses the style of Chinese characters, as the root element'slangattribute does.images:allowUrl,maxBytes,timeoutandthrowOnErrorfor the images and emoji in the markup.allowUrlis how an app keeps request values in image URLs from reaching internal addresses on the Node.js target.fontsentry is{ name, data, weight?, style?, lang? }with the font's bytes, or a font file's URL.weightis any number from 1 to 1000; leaving it out lets a variable font follow each element'sfontWeight.fallbackFonts: falseturns off the Google Fonts downloads described below, for apps that pass their own fonts.Takumi's other options (
format,devicePixelRatio,css,renderer,moduleand so on) are not accepted.Why Takumi
Takumi (
takumi-js) ships a Wasm build with aworkerdexport condition, which the Cloudflare Vite plugin loads as a compiled module in dev and builds, plus a native addon for Node.js and Bun. It takes JSX or HTML and draws straight to pixels, sovoid/ogstays a thin wrapper.Warm render times for 1200 × 630 cards in workerd (Miniflare, median):
The first request in a new isolate takes about 110 ms. With the native addon on Node.js, the same cards take 3–10 ms.
What the wrapper adds
Content-Type, anddebug.Cache-Controlispublic, max-age=0, must-revalidate. The guide shows how to cache image routes withrouting.revalidate.text=and only the characters the image uses, so Google returns one small file. On a deployed Worker, a 45-character Japanese title takes 2 requests and a 26 KB file, against 21 requests and 480 KB for the per-range files. Text too long for one request (about 650 CJK characters) falls back to the per-range files.fallbackFonts: falsewith the app's own fonts avoids it.langnames the language or the text has Hangul. An explicitlangwins over kana, so a Traditional Chinese title with a katakana word stays Chinese.fontWeight: 700draws real bold rather than a thickened regular.packages/void/src/runtime/og-fonts.ts.Node.js, Bun and Deno
Takumi loads its renderer from files next to its own code, which a bundle cannot carry. On these targets the build fails with the install command when the app has no supported
takumi-jsin its own dependencies; the dev server only warns.The app installs
takumi-jsbecause the production install runs on the server, so it fetches the native binary for that OS and CPU. Two alternatives were considered and left out:takumi-jsand the build machine's binary intodist/ssradds about 12 MB and breaks when the build runs on another platform than the server, such as macOS to a Linux container.The build accepts any
takumi-jsin Void's~2.20.0range, so raising that range later asks Node.js apps to update theirs.Workers Free
Apps that don't import
void/ogbundle nothing extra (covered by a test). Takumi's Wasm adds about 4.3 MB (1.9 MB gzipped) to the Worker. A simple card takes around 10 ms of CPU, richer ones 30–80 ms, and the first render in a new isolate more than 100 ms, so the guide tells Workers Free apps to cache image routes with revalidation.takumi-js version
takumi-jsis on~2.20.0. 2.19.0 loads only the first font whoseunicode-rangecovers a character and draws the whole word as .notdef boxes when that font lacks the glyph: with Japanese in the image, "Łódź" renders as boxes. 2.20.0 fixes this: Japanese next to Polish, symbols, mixed scripts, bold Japanese and twemoji render pixel-identical to 2.18.2 with both the native and Wasm backends, and the built-in Geist draws the same code points. The build rejects 2.19.x.packages/void/AGENTS.mdnotes how to check a version before raising the range.Docs
docs/guide/og-images.md, with options, fonts, controlling font downloads, caching, Worker size, and the Node.js, Bun and Deno setup.void/ogin the API reference, a link from thehead()guide, a note in the Node.js, Bun and Deno integration guide, and a task row in thevoidskill.Tests
packages/void/test/unit/og.test.ts(34 tests): defaults and headers, JSX, font weights, options outsideImageResponseOptionsnot reaching Takumi, fallback-font selection andtext=requests (including Han text next to Hangul), the long-text fallback,fallbackFonts: false, weights and subsetting,lang, per-image font isolation, partial fallback download failures, emoji,images.throwOnError, and the Node.js build check.packages/void/test/integration/og-image.test.ts(6 tests): the dev server in workerd, the built Worker in Miniflare (oneCompiledWasmmodule), an app without React, an app withoutvoid/og(no Wasm in its bundle), and the Node.js target, which renders with the app'stakumi-jsand fails the build without it..github/scripts/packed-consumer.mjsrenders an image route from the packed tarballs in dev and preview, and on the Node.js target.🤖 Generated with Claude Code