Skip to Content
Takumi

Astro

Generate Open Graph images for every static Astro page with astro-takumi, or render an Astro component to a PDF from an endpoint.

astro-takumi renders an Open Graph image for every page of an Astro site. During the build, it reads each emitted page and renders a React component or a built-in preset with Takumi. It writes each image next to its HTML file.

Add the integration

astro add adds the integration to your config. Also install React and a font. React describes the layout and never ships to the client. System fonts are unavailable, so declare every font yourself.

npx astro add astro-takumi
npm i -D react @fontsource/roboto

Configure the integration

Pass the fonts and a render function. The presets cover common layouts. Set site so the integration can build absolute image URLs.

astro-takumi runs in astro:build:done, so it only covers statically rendered pages.
astro.config.mjs
import { defineConfig } from "astro/config";
import * as fs from "node:fs";
import { fileURLToPath } from "node:url";
import astroTakumi, { presets } from "astro-takumi";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    astroTakumi({
      options: {
        fonts: [fs.readFileSync(fileURLToPath(import.meta.resolve("@fontsource/roboto/files/roboto-latin-400-normal.woff")))],
      },
      render: presets.blackAndWhite,
    }),
  ],
});

Reference the image from your layout

getImagePath returns the URL of the current page's image.

The build fails if og:title, og:type, or og:image is missing, or if og:image does not match that URL.
src/layouts/Layout.astro
---
import { getImagePath } from "astro-takumi";

const { title } = Astro.props;
const { url, site } = Astro;

const openGraphImageUrl = getImagePath({ url, site });
---

<head>
  <title>{title}</title>
  <meta property="og:title" content={title} />
  <meta property="og:type" content="website" />
  <meta property="og:url" content={url.href} />
  <meta property="og:image" content={openGraphImageUrl} />
</head>

Render a PDF

An endpoint can render an Astro component to a PDF with takumi-pdf. The Container API turns the component into HTML.

npm i takumi-pdf

The Container API returns only the component's markup, and Astro moves a plain <style> block to the page head. Mark the block is:inline so it stays in the HTML. Inline styles are not scoped, so they apply to the whole PDF.

src/components/Invoice.astro
---
const { id, total } = Astro.props;
---

<h1>Invoice {id}</h1>
<p>Total: ${total}</p>

<style is:inline>
  h1 { font-family: Geist; }
</style>
src/pages/invoice.pdf.ts
import type { APIRoute } from "astro";
import { experimental_AstroContainer as AstroContainer } from "astro/container";
import { render } from "takumi-pdf";
import Invoice from "../components/Invoice.astro";

export const GET: APIRoute = async () => {
  const container = await AstroContainer.create();
  const html = await container.renderToString(Invoice, { props: { id: 1042, total: 1290 } });
  const pdf = await render(html, { size: "a4" });

  return new Response(pdf, { headers: { "content-type": "application/pdf" } });
};

With the default static output, astro build writes dist/invoice.pdf at build time. In server output, the endpoint renders on every request.

Next steps

Load more fonts with Fonts. Style the layout with Styles.

Last updated on