astro-opengraph-images 1.18.0 → 1.19.0-dev.10933

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.19.0](https://github.com/shepherdjerred/monorepo/compare/astro-opengraph-images-v1.18.0...astro-opengraph-images-v1.19.0) (2026-08-23)
+
+
+### Features
+
+* **astro-opengraph-images:** add early path filtering ([#2331](https://github.com/shepherdjerred/monorepo/issues/2331)) ([63bbab7](https://github.com/shepherdjerred/monorepo/commit/63bbab7ed1deb40db3628b63a314dc82af524a5e))
+
 ## [1.18.0](https://github.com/shepherdjerred/monorepo/compare/astro-opengraph-images-v1.17.4...astro-opengraph-images-v1.18.0) (2026-08-03)
 
 

package/README.md

@@ -215,9 +215,9 @@ If you're using this project, [open a PR](https://github.com/shepherdjerred/mono
 
 ## Filtering Pages
 
-By default, this integration generates an Open Graph image for every page in your build output. Pass an optional `filter` callback to skip pages — for example, the 404 page, utility routes, or sections where images don't apply.
+By default, this integration generates an Open Graph image for every page in your build output. Pass an optional `pathFilter` callback to skip pages before their output files are read — for example, the 404 page, utility routes, or sections where images don't apply.
 
-The callback receives the same `RenderFunctionInput` as your renderer (pathname, parsed DOM, Open Graph metadata). Return `true` to render the image, `false` to skip it. The callback may be synchronous or return a `Promise<boolean>`.
+The `pathFilter` callback receives the page pathname. Return `true` to continue processing the page and `false` to skip it. The callback may be synchronous or return a `Promise<boolean>`.
 
 ```diff
  import opengraphImages, { presets } from "astro-opengraph-images";
@@ -228,7 +228,7 @@ The callback receives the same `RenderFunctionInput` as your renderer (pathname,
        options: { fonts: [/* ... */] },
        render: presets.blackAndWhite,
 +      // Only generate images for blog posts
-+      filter: ({ pathname }) => pathname.startsWith("/blog/"),
++      pathFilter: ({ pathname }) => pathname.startsWith("/blog/"),
      }),
    ],
  });
@@ -237,16 +237,15 @@ The callback receives the same `RenderFunctionInput` as your renderer (pathname,
 More examples:
 
 ```typescript
-// Exclude utility pages
-filter: ({ pathname }) => !["/404/", "/"].includes(pathname);
+// Exclude utility pages before their HTML is read
+pathFilter: ({ pathname }) => !["/404/", "/"].includes(pathname);
 
-// Filter on DOM content or async data
-filter: async ({ document, pathname }) =>
-  document.querySelector('meta[property="og:image"]') !== null &&
-  pathname.startsWith("/blog/");
+// Filter on DOM content after Open Graph metadata has been extracted
+filter: async ({ document, type }) =>
+  type === "article" && document.querySelector("article") !== null;
 ```
 
-When `verbose: true` is set on `options`, skipped pages are logged.
+Use `pathFilter` when excluded pages may not have the required Open Graph metadata. The metadata-aware `filter` runs only after the output HTML is read, parsed, and strictly extracted, so it is never called for a page missing any of these required tags: `og:title`, `og:url`, `og:type`, or `og:image`. A missing required tag fails the build before `filter` can return `false`. When `verbose: true` is set on `options`, skipped pages are logged.
 
 ## Custom Renderers
 
@@ -564,3 +563,31 @@ Here are some similar libraries using Satori and Astro. I haven't done a feature
 - https://github.com/cijiugechu/astro-satori (Possibly dead, hasn't been updated in a year)
 - https://github.com/kevinzunigacuellar/astro-satori (Possibly dead, hasn't been updated in a year)
 - https://github.com/rumaan/astro-vercel-og (Possibly dead, hasn't been updated in a year)
+
+## Maintainers
+
+This README is hand-maintained; edit it directly.
+
+- **Tests** — `bun run test` (runs `vitest src`).
+- **Preset example images** — build the preset example site first, then render
+  the PNGs from the package root:
+
+  ```bash
+  cd examples/preset && bun install && bun run build && cd ../..
+  bun run src/presets/render-examples.ts   # writes assets/presets/<name>.png
+  ```
+
+  The separate `bun install` is deliberate. `examples/` is intentionally **not**
+  part of the root workspace: both examples declare the package name `example`,
+  so listing them would abort the root install with
+  `Workspace name "example" already exists`. Each example instead installs on
+  its own and pulls this package in through the `postinstall` hook
+  (`scripts/copy-example-deps.ts`), which copies the files named in our
+  `package.json` `files` field — mirroring what `npm pack` ships. That is the
+  point: the examples consume the package the way a published consumer does,
+  and it avoids the recursive symlink a `file:`/`link:` dependency would create
+  for a directory nested inside the package it depends on. Do not "fix" this by
+  adding `examples/*` to the root `workspaces`.
+
+- **Publish** — `bun run publish:npm` (wraps `scripts/publish-npm.ts` at the
+  repo root).

package/dist/hook.d.ts

@@ -1,7 +1,8 @@
-import type { AstroBuildDoneHookInput, FilterFunction, IntegrationOptions, RenderFunction } from "./types.ts";
-export declare function buildDoneHook({ logger, pages, options, dir, render, filter, }: AstroBuildDoneHookInput & {
+import type { AstroBuildDoneHookInput, FilterFunction, IntegrationOptions, PathFilterFunction, RenderFunction } from "./types.ts";
+export declare function buildDoneHook({ logger, pages, options, dir, render, filter, pathFilter, }: AstroBuildDoneHookInput & {
     options: IntegrationOptions;
     render: RenderFunction;
     filter: FilterFunction | undefined;
+    pathFilter: PathFilterFunction | undefined;
 }): Promise<void>;
 //# sourceMappingURL=hook.d.ts.map

package/dist/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAElB,cAAc,EACf,MAAM,YAAY,CAAC;AASpB,wBAAsB,aAAa,CAAC,EAClC,MAAM,EACN,KAAK,EACL,OAAO,EACP,GAAG,EACH,MAAM,EACN,MAAM,GACP,EAAE,uBAAuB,GAAG;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,cAAc,GAAG,SAAS,CAAC;CACpC,iBAMA"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAElB,kBAAkB,EAClB,cAAc,EACf,MAAM,YAAY,CAAC;AASpB,wBAAsB,aAAa,CAAC,EAClC,MAAM,EACN,KAAK,EACL,OAAO,EACP,GAAG,EACH,MAAM,EACN,MAAM,EACN,UAAU,GACX,EAAE,uBAAuB,GAAG;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,cAAc,GAAG,SAAS,CAAC;IACnC,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAC;CAC5C,iBAMA"}

package/dist/hook.js

@@ -6,12 +6,21 @@ import { getFilePath } from "./util.js";
 import { fileURLToPath } from "node:url";
 import * as jsdom from "jsdom";
 import path from "node:path";
-export async function buildDoneHook({ logger, pages, options, dir, render, filter, }) {
+export async function buildDoneHook({ logger, pages, options, dir, render, filter, pathFilter, }) {
     logger.info("Generating Open Graph images");
-    const promises = pages.map((page) => handlePage({ page, options, render, dir, logger, filter }));
+    const promises = pages.map((page) => handlePage({ page, options, render, dir, logger, filter, pathFilter }));
     await Promise.all(promises);
 }
-async function handlePage({ page, options, render, dir, logger, filter, }) {
+async function handlePage({ page, options, render, dir, logger, filter, pathFilter, }) {
+    if (pathFilter) {
+        const shouldRender = await pathFilter(page);
+        if (!shouldRender) {
+            if (options.verbose) {
+                logger.info(`Skipping page ${page.pathname}.`);
+            }
+            return;
+        }
+    }
     // gets the absolute path to the HTML file. E.g. /home/user/project/dist/blog/index.html
     // fileURLToPath() converts the URL to a file path. Without it, the path would start with a leading slash on Windows
     // systems, resulting in an invalid path.

package/dist/hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook.js","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAS5B,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEvC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAClC,MAAM,EACN,KAAK,EACL,OAAO,EACP,GAAG,EACH,MAAM,EACN,MAAM,EACN,UAAU,GAMX;IACC,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAClC,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CACvE,CAAC;IACF,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAYD,KAAK,UAAU,UAAU,CAAC,EACxB,IAAI,EACJ,OAAO,EACP,MAAM,EACN,GAAG,EACH,MAAM,EACN,MAAM,EACN,UAAU,GACM;IAChB,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;QAE5C,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;YACjD,CAAC;YACD,OAAO;QACT,CAAC;IACH,CAAC;IAED,wFAAwF;IACxF,oHAAoH;IACpH,yCAAyC;IACzC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC;QACjC,GAAG,EAAE,aAAa,CAAC,GAAG,CAAC;QACvB,IAAI,EAAE,IAAI,CAAC,QAAQ;KACpB,CAAC,CAAC;IAEH,6CAA6C;IAC7C,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IAErE,sDAAsD;IACtD,MAAM,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;IAE/D,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QAE/C,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;YACjD,CAAC;YACD,OAAO;QACT,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,GAAG,EAAE;QAC3B,IAAI,EAAE;YACJ,eAAe,EAAE,KAAK;SACvB;QACD,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB;KACF,CAAC,CAAC;IAEH,uGAAuG;IACvG,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;IAEpD,kGAAkG;IAClG,4FAA4F;IAC5F,MAAM,eAAe,GAAG,IAAI;SACzB,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;SACrC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAEzB,+FAA+F;IAC/F,MAAM,QAAQ,GAAG,kBAAkB,CACjC,IAAI,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAC7C,CAAC;IAEF,wDAAwD;IACxD,IAAI,QAAQ,KAAK,eAAe,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,4BAA4B,QAAQ,KAAK,QAAQ,yCAAyC,eAAe,IAAI,CAC9G,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,aAAa,eAAe,QAAQ,QAAQ,GAAG,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC"}

package/dist/hook.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hook.test.d.ts.map

package/dist/hook.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.test.d.ts","sourceRoot":"","sources":["../src/hook.test.ts"],"names":[],"mappings":""}

package/dist/hook.test.js

@@ -0,0 +1,217 @@
+import { access, mkdir, mkdtemp, readFile, rm, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createElement } from "react";
+import { expect, test } from "vitest";
+import { buildDoneHook } from "./hook.js";
+import { astroOpenGraphImages } from "./integration.js";
+class TestLogger {
+    options = {
+        destination: {
+            write: (message) => {
+                void message;
+            },
+        },
+        level: "silent",
+    };
+    label = "test";
+    fork(_label) {
+        return new TestLogger();
+    }
+    info(message) {
+        void message;
+    }
+    warn(message) {
+        void message;
+    }
+    error(message) {
+        void message;
+    }
+    debug(message) {
+        void message;
+    }
+    flush() {
+        void this.label;
+    }
+    close() {
+        void this.label;
+    }
+}
+test("an async path filter skips a page before reading its output", async () => {
+    const outputDir = await createTempDir();
+    let pathFilterCalls = 0;
+    let filterCalls = 0;
+    let renderCalls = 0;
+    const pathFilter = async ({ pathname }) => {
+        pathFilterCalls += 1;
+        await Promise.resolve();
+        return pathname !== "/excluded/";
+    };
+    const filter = ({ pathname }) => {
+        filterCalls += 1;
+        return pathname !== "/excluded/";
+    };
+    const render = () => {
+        renderCalls += 1;
+        return null;
+    };
+    const integration = astroOpenGraphImages({
+        options: { fonts: testOptions.fonts },
+        render,
+        filter,
+        pathFilter,
+    });
+    const hook = integration.hooks["astro:build:done"];
+    if (hook === undefined) {
+        throw new Error("Expected astro:build:done hook");
+    }
+    try {
+        await expect(hook({
+            pages: [{ pathname: "/excluded/" }],
+            dir: pathToFileURL(`${outputDir}/`),
+            assets: new Map(),
+            logger: new TestLogger(),
+        })).resolves.toBeUndefined();
+    }
+    finally {
+        await rm(outputDir, { force: true, recursive: true });
+    }
+    expect(pathFilterCalls).toBe(1);
+    expect(filterCalls).toBe(0);
+    expect(renderCalls).toBe(0);
+});
+test("a path-filtered-in page still requires Open Graph metadata", async () => {
+    const outputDir = await createOutputDir("accepted", "<html></html>");
+    let filterCalls = 0;
+    const pathFilter = alwaysPathFilter;
+    const filter = () => {
+        filterCalls += 1;
+        return true;
+    };
+    const render = emptyRender;
+    try {
+        await expect(buildDoneHook({
+            pages: [{ pathname: "/accepted/" }],
+            dir: pathToFileURL(`${outputDir}/`),
+            assets: new Map(),
+            logger: new TestLogger(),
+            options: testOptions,
+            render,
+            filter,
+            pathFilter,
+        })).rejects.toThrow("Missing required meta tags");
+    }
+    finally {
+        await rm(outputDir, { force: true, recursive: true });
+    }
+    expect(filterCalls).toBe(0);
+});
+test("an accepted page with Open Graph metadata renders an image", async () => {
+    const outputDir = await createOutputDir("rendered", `<!doctype html>
+      <html>
+        <head>
+          <meta property="og:title" content="Rendered page" />
+          <meta property="og:url" content="http://example.com/rendered/" />
+          <meta property="og:type" content="website" />
+          <meta property="og:image" content="http://example.com/rendered/index.png" />
+        </head>
+      </html>`);
+    let filterCalls = 0;
+    let renderCalls = 0;
+    const pathFilter = alwaysPathFilter;
+    const filter = ({ pathname }) => {
+        filterCalls += 1;
+        return pathname === "/rendered/";
+    };
+    const render = () => {
+        renderCalls += 1;
+        return createElement("div");
+    };
+    try {
+        await expect(buildDoneHook({
+            pages: [{ pathname: "/rendered/" }],
+            dir: pathToFileURL(`${outputDir}/`),
+            assets: new Map(),
+            logger: new TestLogger(),
+            options: testOptions,
+            render,
+            filter,
+            pathFilter,
+        })).resolves.toBeUndefined();
+        await access(path.join(outputDir, "rendered", "index.png"));
+    }
+    finally {
+        await rm(outputDir, { force: true, recursive: true });
+    }
+    expect(filterCalls).toBe(1);
+    expect(renderCalls).toBe(1);
+});
+test("the metadata-aware filter can skip a valid page", async () => {
+    const outputDir = await createOutputDir("metadata-skipped", renderedPageHtml("metadata-skipped"));
+    let filterCalls = 0;
+    let renderCalls = 0;
+    const pathFilter = alwaysPathFilter;
+    const filter = ({ title }) => {
+        filterCalls += 1;
+        expect(title).toBe("Rendered page");
+        return false;
+    };
+    const render = () => {
+        renderCalls += 1;
+        return createElement("div");
+    };
+    try {
+        await expect(buildDoneHook({
+            pages: [{ pathname: "/metadata-skipped/" }],
+            dir: pathToFileURL(`${outputDir}/`),
+            assets: new Map(),
+            logger: new TestLogger(),
+            options: testOptions,
+            render,
+            filter,
+            pathFilter,
+        })).resolves.toBeUndefined();
+        await expect(access(path.join(outputDir, "metadata-skipped", "index.png"))).rejects.toThrow();
+    }
+    finally {
+        await rm(outputDir, { force: true, recursive: true });
+    }
+    expect(filterCalls).toBe(1);
+    expect(renderCalls).toBe(0);
+});
+const testOptions = {
+    width: 1200,
+    height: 630,
+    verbose: false,
+    fonts: [
+        {
+            data: await readFile(path.join(import.meta.dirname, "../node_modules/@fontsource/roboto/files/roboto-latin-400-normal.woff")),
+            name: "Roboto",
+            weight: 400,
+        },
+    ],
+};
+const alwaysPathFilter = () => true;
+const emptyRender = () => null;
+async function createOutputDir(page, html = renderedPageHtml(page)) {
+    const outputDir = await createTempDir();
+    await mkdir(path.join(outputDir, page), { recursive: true });
+    await writeFile(path.join(outputDir, page, "index.html"), html);
+    return outputDir;
+}
+async function createTempDir() {
+    return await mkdtemp(path.join(tmpdir(), "astro-opengraph-images-"));
+}
+function renderedPageHtml(page) {
+    return `<!doctype html>
+    <html>
+      <head>
+        <meta property="og:title" content="Rendered page" />
+        <meta property="og:url" content="http://example.com/${page}/" />
+        <meta property="og:type" content="website" />
+        <meta property="og:image" content="http://example.com/${page}/index.png" />
+      </head>
+    </html>`;
+}
+//# sourceMappingURL=hook.test.js.map

package/dist/hook.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.test.js","sourceRoot":"","sources":["../src/hook.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { getImagePath as importedGetImagePath } from "./util.ts";
 import { astroOpenGraphImages } from "./integration.ts";
-import type { IntegrationInput as _IntegrationInput, IntegrationDefaults as _IntegrationDefaults, PartialIntegrationOptions as _PartialIntegrationOptions, IntegrationOptions as _IntegrationOptions, Page as _Page, AstroBuildDoneHookInput as _AstroBuildDoneHookInput, RenderFunctionInput as _RenderFunctionInput, RenderFunction as _RenderFunction, FilterFunction as _FilterFunction, PageDetails as _PageDetails, SatoriWeight as _SatoriWeight, SatoriFontStyle as _SatoriFontStyle, SatoriFontOptions as _SatoriFontOptions, SatoriOptions as _SatoriOptions } from "./types.ts";
+import type { IntegrationInput as _IntegrationInput, IntegrationDefaults as _IntegrationDefaults, PartialIntegrationOptions as _PartialIntegrationOptions, IntegrationOptions as _IntegrationOptions, Page as _Page, AstroBuildDoneHookInput as _AstroBuildDoneHookInput, RenderFunctionInput as _RenderFunctionInput, RenderFunction as _RenderFunction, FilterFunction as _FilterFunction, PathFilterFunction as _PathFilterFunction, PageDetails as _PageDetails, SatoriWeight as _SatoriWeight, SatoriFontStyle as _SatoriFontStyle, SatoriFontOptions as _SatoriFontOptions, SatoriOptions as _SatoriOptions } from "./types.ts";
 export declare const presets: {
     blackAndWhite: typeof import("./presets/black-and-white.tsx").blackAndWhite;
     gradients: typeof import("./presets/gradients.tsx").gradients;
@@ -25,6 +25,7 @@ export type AstroBuildDoneHookInput = _AstroBuildDoneHookInput;
 export type RenderFunctionInput = _RenderFunctionInput;
 export type RenderFunction = _RenderFunction;
 export type FilterFunction = _FilterFunction;
+export type PathFilterFunction = _PathFilterFunction;
 export type PageDetails = _PageDetails;
 export type SatoriWeight = _SatoriWeight;
 export type SatoriFontStyle = _SatoriFontStyle;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,gBAAgB,IAAI,iBAAiB,EACrC,mBAAmB,IAAI,oBAAoB,EAC3C,yBAAyB,IAAI,0BAA0B,EACvD,kBAAkB,IAAI,mBAAmB,EACzC,IAAI,IAAI,KAAK,EACb,uBAAuB,IAAI,wBAAwB,EACnD,mBAAmB,IAAI,oBAAoB,EAC3C,cAAc,IAAI,eAAe,EACjC,cAAc,IAAI,eAAe,EACjC,WAAW,IAAI,YAAY,EAC3B,YAAY,IAAI,aAAa,EAC7B,eAAe,IAAI,gBAAgB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,aAAa,IAAI,cAAc,EAChC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,OAAO;;;;;;;;;;;;CAAkB,CAAC;AACvC,eAAO,MAAM,YAAY,6BAAuB,CAAC;eAClC,oBAAoB;AAEnC,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AACjD,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AACvD,MAAM,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AACnE,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AACrD,MAAM,MAAM,IAAI,GAAG,KAAK,CAAC;AACzB,MAAM,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAC/D,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC;AACvC,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AACzC,MAAM,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AACnD,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,gBAAgB,IAAI,iBAAiB,EACrC,mBAAmB,IAAI,oBAAoB,EAC3C,yBAAyB,IAAI,0BAA0B,EACvD,kBAAkB,IAAI,mBAAmB,EACzC,IAAI,IAAI,KAAK,EACb,uBAAuB,IAAI,wBAAwB,EACnD,mBAAmB,IAAI,oBAAoB,EAC3C,cAAc,IAAI,eAAe,EACjC,cAAc,IAAI,eAAe,EACjC,kBAAkB,IAAI,mBAAmB,EACzC,WAAW,IAAI,YAAY,EAC3B,YAAY,IAAI,aAAa,EAC7B,eAAe,IAAI,gBAAgB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,aAAa,IAAI,cAAc,EAChC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,OAAO;;;;;;;;;;;;CAAkB,CAAC;AACvC,eAAO,MAAM,YAAY,6BAAuB,CAAC;eAClC,oBAAoB;AAEnC,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AACjD,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AACvD,MAAM,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AACnE,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AACrD,MAAM,MAAM,IAAI,GAAG,KAAK,CAAC;AACzB,MAAM,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAC/D,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAC7C,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC;AACvC,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AACzC,MAAM,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AACnD,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAkBxD,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AACjD,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAmBxD,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AACjD,eAAe,oBAAoB,CAAC"}

package/dist/integration.d.ts

@@ -1,4 +1,4 @@
 import type { AstroIntegration } from "astro";
 import type { IntegrationInput } from "./types.ts";
-export declare function astroOpenGraphImages({ options, render, filter, }: IntegrationInput): AstroIntegration;
+export declare function astroOpenGraphImages({ options, render, filter, pathFilter, }: IntegrationInput): AstroIntegration;
 //# sourceMappingURL=integration.d.ts.map

package/dist/integration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../src/integration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAGV,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AASpB,wBAAgB,oBAAoB,CAAC,EACnC,OAAO,EACP,MAAM,EACN,MAAM,GACP,EAAE,gBAAgB,GAAG,gBAAgB,CAgBrC"}
+{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../src/integration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAGV,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AASpB,wBAAgB,oBAAoB,CAAC,EACnC,OAAO,EACP,MAAM,EACN,MAAM,EACN,UAAU,GACX,EAAE,gBAAgB,GAAG,gBAAgB,CAiBrC"}

package/dist/integration.js

@@ -4,7 +4,7 @@ const defaults = {
     height: 630,
     verbose: false,
 };
-export function astroOpenGraphImages({ options, render, filter, }) {
+export function astroOpenGraphImages({ options, render, filter, pathFilter, }) {
     const optionsWithDefaults = { ...defaults, ...options };
     return {
         name: "astro-opengraph-images",
@@ -15,6 +15,7 @@ export function astroOpenGraphImages({ options, render, filter, }) {
                     options: optionsWithDefaults,
                     render,
                     filter,
+                    pathFilter,
                 });
             },
         },

package/dist/integration.js.map

@@ -1 +1 @@
-{"version":3,"file":"integration.js","sourceRoot":"","sources":["../src/integration.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,QAAQ,GAAwB;IACpC,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,KAAK;CACf,CAAC;AAEF,MAAM,UAAU,oBAAoB,CAAC,EACnC,OAAO,EACP,MAAM,EACN,MAAM,GACW;IACjB,MAAM,mBAAmB,GAAuB,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;IAE5E,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE;YACL,kBAAkB,EAAE,KAAK,EAAE,KAA8B,EAAE,EAAE;gBAC3D,OAAO,aAAa,CAAC;oBACnB,GAAG,KAAK;oBACR,OAAO,EAAE,mBAAmB;oBAC5B,MAAM;oBACN,MAAM;iBACP,CAAC,CAAC;YACL,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"integration.js","sourceRoot":"","sources":["../src/integration.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,QAAQ,GAAwB;IACpC,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,KAAK;CACf,CAAC;AAEF,MAAM,UAAU,oBAAoB,CAAC,EACnC,OAAO,EACP,MAAM,EACN,MAAM,EACN,UAAU,GACO;IACjB,MAAM,mBAAmB,GAAuB,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;IAE5E,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE;YACL,kBAAkB,EAAE,KAAK,EAAE,KAA8B,EAAE,EAAE;gBAC3D,OAAO,aAAa,CAAC;oBACnB,GAAG,KAAK;oBACR,OAAO,EAAE,mBAAmB;oBAC5B,MAAM;oBACN,MAAM;oBACN,UAAU;iBACX,CAAC,CAAC;YACL,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export type IntegrationInput = {
     options: PartialIntegrationOptions;
     render: RenderFunction;
     filter?: FilterFunction;
+    pathFilter?: PathFilterFunction;
 };
 /** When applied to PartialIntegrationOptions this type equals IntegrationOptions */
 export type IntegrationDefaults = {
@@ -25,6 +26,8 @@ export type IntegrationOptions = PartialIntegrationOptions & IntegrationDefaults
 export type Page = {
     pathname: string;
 };
+/** A function that filters pages before their output files are read */
+export type PathFilterFunction = (input: Page) => Promise<boolean> | boolean;
 /** The input Astro passes to the build done hook */
 export type AstroBuildDoneHookInput = Parameters<BaseIntegrationHooks["astro:build:done"]>[0];
 /** The input arguments to a `RenderFunction` */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,yBAAyB,CAAC;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,EAC5B,QAAQ,CACT,GACC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GACxD,mBAAmB,CAAC;AAEtB,+CAA+C;AAC/C,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,oDAAoD;AACpD,MAAM,MAAM,uBAAuB,GAAG,UAAU,CAC9C,oBAAoB,CAAC,kBAAkB,CAAC,CACzC,CAAC,CAAC,CAAC,CAAC;AAEL,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,QAAQ,CAAC;CACpB,GAAG,WAAW,CAAC;AAEhB,4FAA4F;AAC5F,MAAM,MAAM,cAAc,GAAG,CAC3B,KAAK,EAAE,mBAAmB,KACvB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEhC,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,CAC3B,KAAK,EAAE,mBAAmB,KACvB,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAEpC,qCAAqC;AACrC,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AAEpC,+BAA+B;AAC/B,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAC/E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AACF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACxC,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,CACpB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC,CAAC;CAC5C,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -17,17 +17,16 @@
     "url": "https://github.com/shepherdjerred/monorepo/issues"
   },
   "type": "module",
-  "version": "1.18.0",
+  "version": "1.19.0-dev.10933",
   "imports": {
     "#src/*": "./src/*"
   },
   "scripts": {
-    "lint": "eslint src generate-readme.ts generate-readme-core.ts generate-readme*.test.ts --cache",
+    "lint": "eslint src --cache",
     "build": "PATH=node_modules/@typescript/native/bin:$PATH tsc",
     "watch": "PATH=node_modules/@typescript/native/bin:$PATH tsc -w",
-    "test": "vitest src && bun test generate-readme*.test.ts",
-    "test:coverage": "bun test --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage --config ../../scripts/bunfig.coverage.toml --coverage generate-readme.test.ts",
-    "typecheck": "PATH=node_modules/@typescript/native/bin:$PATH tsc --noEmit && PATH=node_modules/@typescript/native/bin:$PATH tsc --noEmit -p tsconfig.scripts.json",
+    "test": "bun --no-install --bun vitest --config ../../vitest.config.ts run src",
+    "typecheck": "PATH=node_modules/@typescript/native/bin:$PATH tsc --noEmit",
     "publish:npm": "bun ../../scripts/publish-npm.ts .",
     "test:ci": "bun ../../scripts/run-ci-test.ts",
     "test:report": "CI_TEST_COVERAGE=1 bun ../../scripts/run-ci-test.ts"
@@ -73,17 +72,17 @@
     "@shepherdjerred/eslint-config": "0.3.0",
     "@tsconfig/node24": "^24.0.4",
     "@tsconfig/strictest": "^2.0.8",
-    "@types/bun": "^1.3.13",
-    "@types/jsdom": "^28.0.1",
+    "@types/bun": "1.4.0",
+    "@types/jsdom": "^30.0.0",
     "@types/node": "^26.1.1",
-    "@types/react": "^19.2.17",
+    "@types/react": "^19.2.18",
     "@typescript/native": "npm:typescript@7.0.2",
     "astro": "^7.1.5",
     "eslint": "^10.3.0",
     "jiti": "^2.7.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "@vitest/coverage-istanbul": "4.1.9"
+    "vitest": "4.1.10",
+    "@vitest/coverage-istanbul": "4.1.10"
   },
   "files": [
     "dist",

package/src/hook.test.ts

@@ -0,0 +1,277 @@
+import type { AstroIntegrationLogger } from "astro";
+import {
+  access,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createElement } from "react";
+import { expect, test } from "vitest";
+import { buildDoneHook } from "./hook.ts";
+import { astroOpenGraphImages } from "./integration.ts";
+import type {
+  FilterFunction,
+  IntegrationOptions,
+  PathFilterFunction,
+  RenderFunction,
+} from "./types.ts";
+
+class TestLogger implements AstroIntegrationLogger {
+  readonly options = {
+    destination: {
+      write: (message: unknown) => {
+        void message;
+      },
+    },
+    level: "silent" as const,
+  };
+  readonly label = "test";
+
+  fork(_label: string): TestLogger {
+    return new TestLogger();
+  }
+
+  info(message: string): void {
+    void message;
+  }
+
+  warn(message: string): void {
+    void message;
+  }
+
+  error(message: string): void {
+    void message;
+  }
+
+  debug(message: string): void {
+    void message;
+  }
+
+  flush(): void {
+    void this.label;
+  }
+
+  close(): void {
+    void this.label;
+  }
+}
+
+test("an async path filter skips a page before reading its output", async () => {
+  const outputDir = await createTempDir();
+  let pathFilterCalls = 0;
+  let filterCalls = 0;
+  let renderCalls = 0;
+
+  const pathFilter: PathFilterFunction = async ({ pathname }) => {
+    pathFilterCalls += 1;
+    await Promise.resolve();
+    return pathname !== "/excluded/";
+  };
+  const filter: FilterFunction = ({ pathname }) => {
+    filterCalls += 1;
+    return pathname !== "/excluded/";
+  };
+  const render: RenderFunction = () => {
+    renderCalls += 1;
+    return null;
+  };
+  const integration = astroOpenGraphImages({
+    options: { fonts: testOptions.fonts },
+    render,
+    filter,
+    pathFilter,
+  });
+  const hook = integration.hooks["astro:build:done"];
+
+  if (hook === undefined) {
+    throw new Error("Expected astro:build:done hook");
+  }
+
+  try {
+    await expect(
+      hook({
+        pages: [{ pathname: "/excluded/" }],
+        dir: pathToFileURL(`${outputDir}/`),
+        assets: new Map(),
+        logger: new TestLogger(),
+      }),
+    ).resolves.toBeUndefined();
+  } finally {
+    await rm(outputDir, { force: true, recursive: true });
+  }
+
+  expect(pathFilterCalls).toBe(1);
+  expect(filterCalls).toBe(0);
+  expect(renderCalls).toBe(0);
+});
+
+test("a path-filtered-in page still requires Open Graph metadata", async () => {
+  const outputDir = await createOutputDir("accepted", "<html></html>");
+  let filterCalls = 0;
+  const pathFilter = alwaysPathFilter;
+  const filter: FilterFunction = () => {
+    filterCalls += 1;
+    return true;
+  };
+  const render = emptyRender;
+
+  try {
+    await expect(
+      buildDoneHook({
+        pages: [{ pathname: "/accepted/" }],
+        dir: pathToFileURL(`${outputDir}/`),
+        assets: new Map(),
+        logger: new TestLogger(),
+        options: testOptions,
+        render,
+        filter,
+        pathFilter,
+      }),
+    ).rejects.toThrow("Missing required meta tags");
+  } finally {
+    await rm(outputDir, { force: true, recursive: true });
+  }
+
+  expect(filterCalls).toBe(0);
+});
+
+test("an accepted page with Open Graph metadata renders an image", async () => {
+  const outputDir = await createOutputDir(
+    "rendered",
+    `<!doctype html>
+      <html>
+        <head>
+          <meta property="og:title" content="Rendered page" />
+          <meta property="og:url" content="http://example.com/rendered/" />
+          <meta property="og:type" content="website" />
+          <meta property="og:image" content="http://example.com/rendered/index.png" />
+        </head>
+      </html>`,
+  );
+  let filterCalls = 0;
+  let renderCalls = 0;
+  const pathFilter = alwaysPathFilter;
+  const filter: FilterFunction = ({ pathname }) => {
+    filterCalls += 1;
+    return pathname === "/rendered/";
+  };
+  const render: RenderFunction = () => {
+    renderCalls += 1;
+    return createElement("div");
+  };
+
+  try {
+    await expect(
+      buildDoneHook({
+        pages: [{ pathname: "/rendered/" }],
+        dir: pathToFileURL(`${outputDir}/`),
+        assets: new Map(),
+        logger: new TestLogger(),
+        options: testOptions,
+        render,
+        filter,
+        pathFilter,
+      }),
+    ).resolves.toBeUndefined();
+    await access(path.join(outputDir, "rendered", "index.png"));
+  } finally {
+    await rm(outputDir, { force: true, recursive: true });
+  }
+
+  expect(filterCalls).toBe(1);
+  expect(renderCalls).toBe(1);
+});
+
+test("the metadata-aware filter can skip a valid page", async () => {
+  const outputDir = await createOutputDir(
+    "metadata-skipped",
+    renderedPageHtml("metadata-skipped"),
+  );
+  let filterCalls = 0;
+  let renderCalls = 0;
+  const pathFilter = alwaysPathFilter;
+  const filter: FilterFunction = ({ title }) => {
+    filterCalls += 1;
+    expect(title).toBe("Rendered page");
+    return false;
+  };
+  const render: RenderFunction = () => {
+    renderCalls += 1;
+    return createElement("div");
+  };
+
+  try {
+    await expect(
+      buildDoneHook({
+        pages: [{ pathname: "/metadata-skipped/" }],
+        dir: pathToFileURL(`${outputDir}/`),
+        assets: new Map(),
+        logger: new TestLogger(),
+        options: testOptions,
+        render,
+        filter,
+        pathFilter,
+      }),
+    ).resolves.toBeUndefined();
+    await expect(
+      access(path.join(outputDir, "metadata-skipped", "index.png")),
+    ).rejects.toThrow();
+  } finally {
+    await rm(outputDir, { force: true, recursive: true });
+  }
+
+  expect(filterCalls).toBe(1);
+  expect(renderCalls).toBe(0);
+});
+
+const testOptions: IntegrationOptions = {
+  width: 1200,
+  height: 630,
+  verbose: false,
+  fonts: [
+    {
+      data: await readFile(
+        path.join(
+          import.meta.dirname,
+          "../node_modules/@fontsource/roboto/files/roboto-latin-400-normal.woff",
+        ),
+      ),
+      name: "Roboto",
+      weight: 400,
+    },
+  ],
+};
+
+const alwaysPathFilter: PathFilterFunction = () => true;
+const emptyRender: RenderFunction = () => null;
+
+async function createOutputDir(
+  page: string,
+  html = renderedPageHtml(page),
+): Promise<string> {
+  const outputDir = await createTempDir();
+  await mkdir(path.join(outputDir, page), { recursive: true });
+  await writeFile(path.join(outputDir, page, "index.html"), html);
+  return outputDir;
+}
+
+async function createTempDir(): Promise<string> {
+  return await mkdtemp(path.join(tmpdir(), "astro-opengraph-images-"));
+}
+
+function renderedPageHtml(page: string): string {
+  return `<!doctype html>
+    <html>
+      <head>
+        <meta property="og:title" content="Rendered page" />
+        <meta property="og:url" content="http://example.com/${page}/" />
+        <meta property="og:type" content="website" />
+        <meta property="og:image" content="http://example.com/${page}/index.png" />
+      </head>
+    </html>`;
+}

package/src/hook.ts

@@ -5,6 +5,7 @@ import type {
   FilterFunction,
   IntegrationOptions,
   Page,
+  PathFilterFunction,
   RenderFunction,
 } from "./types.ts";
 import * as fs from "node:fs/promises";
@@ -22,14 +23,16 @@ export async function buildDoneHook({
   dir,
   render,
   filter,
+  pathFilter,
 }: AstroBuildDoneHookInput & {
   options: IntegrationOptions;
   render: RenderFunction;
   filter: FilterFunction | undefined;
+  pathFilter: PathFilterFunction | undefined;
 }) {
   logger.info("Generating Open Graph images");
   const promises = pages.map((page) =>
-    handlePage({ page, options, render, dir, logger, filter }),
+    handlePage({ page, options, render, dir, logger, filter, pathFilter }),
   );
   await Promise.all(promises);
 }
@@ -41,6 +44,7 @@ type HandlePageInput = {
   dir: URL;
   logger: AstroIntegrationLogger;
   filter: FilterFunction | undefined;
+  pathFilter: PathFilterFunction | undefined;
 };
 
 async function handlePage({
@@ -50,7 +54,19 @@ async function handlePage({
   dir,
   logger,
   filter,
+  pathFilter,
 }: HandlePageInput) {
+  if (pathFilter) {
+    const shouldRender = await pathFilter(page);
+
+    if (!shouldRender) {
+      if (options.verbose) {
+        logger.info(`Skipping page ${page.pathname}.`);
+      }
+      return;
+    }
+  }
+
   // gets the absolute path to the HTML file. E.g. /home/user/project/dist/blog/index.html
   // fileURLToPath() converts the URL to a file path. Without it, the path would start with a leading slash on Windows
   // systems, resulting in an invalid path.

package/src/index.ts

@@ -11,6 +11,7 @@ import type {
   RenderFunctionInput as _RenderFunctionInput,
   RenderFunction as _RenderFunction,
   FilterFunction as _FilterFunction,
+  PathFilterFunction as _PathFilterFunction,
   PageDetails as _PageDetails,
   SatoriWeight as _SatoriWeight,
   SatoriFontStyle as _SatoriFontStyle,
@@ -31,6 +32,7 @@ export type AstroBuildDoneHookInput = _AstroBuildDoneHookInput;
 export type RenderFunctionInput = _RenderFunctionInput;
 export type RenderFunction = _RenderFunction;
 export type FilterFunction = _FilterFunction;
+export type PathFilterFunction = _PathFilterFunction;
 export type PageDetails = _PageDetails;
 export type SatoriWeight = _SatoriWeight;
 export type SatoriFontStyle = _SatoriFontStyle;

package/src/integration.ts

@@ -17,6 +17,7 @@ export function astroOpenGraphImages({
   options,
   render,
   filter,
+  pathFilter,
 }: IntegrationInput): AstroIntegration {
   const optionsWithDefaults: IntegrationOptions = { ...defaults, ...options };
 
@@ -29,6 +30,7 @@ export function astroOpenGraphImages({
           options: optionsWithDefaults,
           render,
           filter,
+          pathFilter,
         });
       },
     },

package/src/types.ts

@@ -5,6 +5,7 @@ export type IntegrationInput = {
   options: PartialIntegrationOptions;
   render: RenderFunction;
   filter?: FilterFunction;
+  pathFilter?: PathFilterFunction;
 };
 
 /** When applied to PartialIntegrationOptions this type equals IntegrationOptions */
@@ -36,6 +37,9 @@ export type Page = {
   pathname: string;
 };
 
+/** A function that filters pages before their output files are read */
+export type PathFilterFunction = (input: Page) => Promise<boolean> | boolean;
+
 /** The input Astro passes to the build done hook */
 export type AstroBuildDoneHookInput = Parameters<
   BaseIntegrationHooks["astro:build:done"]

package/README.md.tmpl

@@ -1,308 +0,0 @@
-<div align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.rawgit.com/shepherdjerred/astro-opengraph-images/main/assets/logo-dark.png">
-    <source media="(prefers-color-scheme: light)" srcset="https://cdn.rawgit.com/shepherdjerred/astro-opengraph-images/main/assets/logo-light.png">
-    <img alt="project logo" src="https://cdn.rawgit.com/shepherdjerred/astro-opengraph-images/main/assets/logo-light.png" height=75>
-  </picture>
-
-[![astro-opengraph-images](https://img.shields.io/npm/v/astro-opengraph-images.svg)](https://www.npmjs.com/package/astro-opengraph-images)
-
-Generate Open Graph images for your Astro site.
-
-This project is actively maintained. If you have a feature request or need help, please [create an issue](https://github.com/shepherdjerred/monorepo/issues/new).
-
-</div>
-
-## What is Open Graph?
-
-[Open Graph](https://ogp.me/) is a protocol created by Facebook. It allows pages on your site to be richly embedded into other sites and applications.
-
-You've probably seen this in action when posting a link on Facebook, Twitter, Slack, iMessage, or Discord. Links posted in supported applications will display the Open Graph metadata which often includes an image. This library will generate those images for you.
-
-## Features
-
-> [!WARNING]
-> This integration has only been tested with statically rendered sites. It is untested with server-side rendering.
-
-- Written in TypeScript
-- Generate Open Graph images for every page on your site.
-- Use a preset renderer to get started quickly.
-- Images are fully customizable using [Satori](https://github.com/vercel/satori).
-- Use React/JSX + Tailwind syntax or vanilla JavaScript to define your own custom images.
-- Supports both static pages and Astro content collections.
-- Pages can be written in Markdown, MDX, HTML, or any other format.
-
-## Quick Start
-
-To better illustrate these steps, I've created a [video](https://www.loom.com/share/a66a65be8a4e48ec8612b78489db590d?sid=3e9f7cd6-68ec-49da-b942-75eb4608cb5e) following them to help others follow along.
-
-1. Add this integration to your Astro config:
-
-   - Option 1: use the `astro` command:
-
-     ```bash
-     npx astro add astro-opengraph-images
-     ```
-
-   - Option 2: install the package and add the integration to your Astro config:
-
-     ```bash
-     npm i astro-opengraph-images
-     ```
-
-     ```diff
-     +import opengraphImages from "astro-opengraph-images";
-
-     export default defineConfig({
-       integrations: [
-     +    opengraphImages()
-       ],
-     });
-     ```
-
-1. Install React. React is used by the presets, and can be used to easily author custom images. Note that React is only used for generating the images and will not be shipped to clients.
-
-   ```bash
-   npm i -D react
-   ```
-
-1. Install the fonts you want to use. Fonts must be explicitly declared to be used for images. System fonts are _not_ available. For this quick start guide, we'll install the [Roboto](https://fontsource.org/fonts/roboto) font:
-
-    ```bash
-    npm i @fontsource/roboto
-    ```
-
-    You can find more fonts on [Fontsource](https://fontsource.org/), or you can use any font file that you have. See [Satori's font documentation](https://github.com/vercel/satori?tab=readme-ov-file#fonts) for more information.
-
-1. Configure the integration in your Astro config:
-
-   ```diff
-   -import opengraphImages from "astro-opengraph-images";
-   +import opengraphImages, { presets } from "astro-opengraph-images";
-
-   export default defineConfig({
-     integrations: [
-   -    opengraphImages()
-   +    opengraphImages({
-   +      options: {
-   +        fonts: [
-   +          {
-   +            name: "Roboto",
-   +            weight: 400,
-   +            style: "normal",
-   +            data: fs.readFileSync("node_modules/@fontsource/roboto/files/roboto-latin-400-normal.woff"),
-   +          },
-   +        ],
-   +      },
-   +      render: presets.blackAndWhite,
-   +    }),
-     ],
-   });
-   ```
-
-1. Set the [`site`](https://docs.astro.build/en/reference/configuration-reference/#site) property in your Astro config:
-
-   Open Graph requires URLs to be absolute, including the domain your site is hosted at. This integration uses the site defined in your Astro config to create the correct URLs for Open Graph which is `site` must be defined.
-
-   ```diff
-   export default defineConfig({
-   +  site: "https://<your site>.com",
-     integrations: [
-       opengraphImages({
-         options: {
-           fonts: [
-             {
-               name: "Roboto",
-               weight: 400,
-               style: "normal",
-               data: fs.readFileSync("node_modules/@fontsource/roboto/files/roboto-latin-400-normal.woff"),
-             },
-           ],
-         },
-         render: presets.blackAndWhite,
-       }),
-     ],
-   });
-   ```
-
-1. Update your main Astro layout with the appropriate `meta` tags. The [Open Graph site](https://ogp.me/) has more information possible tags.
-
-   The following `meta` tags must be defined:
-
-   * `og:title`
-     * This field may be used when generating images.
-   * `og:type`
-     * See the [Open Graph documentation](https://ogp.me/#types) for valid values.
-   * `og:image`
-     * Set this to the return value of `getImagePath` (example shown below).
-     * If the value of `og:image` does not match what this integration expects then your site will fail to build. This will ensure your site is correctly configured to display Open Graph images.
-   * `og:description`
-     * Optional. This field may be used when generating images.
-
-   Your site will fail to build if the tags above are not set.
-
-   * Option 1: Use the [`astro-seo`](https://github.com/jonasmerlin/astro-seo) package:
-
-     Install the `astro-seo` package:
-
-     ```bash
-     npm i astro-seo
-     ```
-
-     Update your Astro layout to use the `SEO` component:
-
-     ```diff
-     ---
-     +import { SEO } from "astro-seo";
-     +import { getImagePath } from "astro-opengraph-images";
-
-     interface Props {
-       title: string;
-     }
-
-     const { title } = Astro.props;
-     +const { url, site } = Astro;
-     +const openGraphImageUrl = getImagePath({ url, site });
-     ---
-
-     <!doctype html>
-     <html lang="en">
-       <head>
-         <meta charset="UTF-8" />
-         <meta name="description" content="Astro description" />
-         <meta name="viewport" content="width=device-width" />
-         <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-         <meta name="generator" content={Astro.generator} />
-         <title>{title}</title>
-
-     +    <SEO
-     +      openGraph={
-     +        {
-     +          basic: {
-     +            title: title,
-     +            type: "website",
-     +            image: openGraphImageUrl,
-     +            url: url,
-     +          },
-     +          optional: {
-     +            description: "My page description",
-     +          },
-     +        }
-     +      }
-     +    />
-       </head>
-       <body>
-         <slot />
-       </body>
-     </html>
-     ```
-
-   * Option 2: Manually add the `meta` tags to your Astro layout.
-
-1. Build your site. You should see a `.png` file next to each `.html` page in your `dist` folder. Double-check that the `og:image` proprety in your `.html` file matches the path to the `.png` file.
-
-1. Deploy your site. You can verify that your images are correct by:
-
-    * Sending a link to your site in an application that supports Open Graph like iMessage, Slack, Discord, etc.
-    * Visit [opengraph.xyz](http://opengraph.xyz/) and test your site.
-
-## Examples
-
-There are example sites using this integration under [`examples/`](https://github.com/shepherdjerred/monorepo/tree/main/packages/astro-opengraph-images/examples).
-
-### Sites Using This
-
-If you're using this project, [open a PR](https://github.com/shepherdjerred/monorepo/compare) to add your site to this list.
-
-* [sjer.red](https://sjer.red) ([source](https://github.com/shepherdjerred/monorepo))
-
-## Filtering Pages
-
-By default, this integration generates an Open Graph image for every page in your build output. Pass an optional `filter` callback to skip pages — for example, the 404 page, utility routes, or sections where images don't apply.
-
-The callback receives the same `RenderFunctionInput` as your renderer (pathname, parsed DOM, Open Graph metadata). Return `true` to render the image, `false` to skip it. The callback may be synchronous or return a `Promise<boolean>`.
-
-```diff
- import opengraphImages, { presets } from "astro-opengraph-images";
-
- export default defineConfig({
-   integrations: [
-     opengraphImages({
-       options: { fonts: [/* ... */] },
-       render: presets.blackAndWhite,
-+      // Only generate images for blog posts
-+      filter: ({ pathname }) => pathname.startsWith("/blog/"),
-     }),
-   ],
- });
-```
-
-More examples:
-
-```typescript
-// Exclude utility pages
-filter: ({ pathname }) => !["/404/", "/"].includes(pathname);
-
-// Filter on DOM content or async data
-filter: async ({ document, pathname }) =>
-  document.querySelector('meta[property="og:image"]') !== null &&
-  pathname.startsWith("/blog/");
-```
-
-When `verbose: true` is set on `options`, skipped pages are logged.
-
-## Custom Renderers
-
-You can create your own custom images with a render function. Take a look at how [a preset](https://github.com/shepherdjerred/monorepo/blob/main/packages/astro-opengraph-images/src/presets/blackAndWhite.tsx) works.
-
-Renderers have access to the page's DOM using [jsdom](https://github.com/jsdom/jsdom). You can use this to render your Open Graph image using any of the content from the associated HTML page. An example of this is shown in the [custom property preset](https://github.com/shepherdjerred/monorepo/blob/main/packages/astro-opengraph-images/src/presets/customProperty.tsx) which shows a preview of the page's body text in the Open Graph image.
-
-This library uses [Satori](https://github.com/vercel/satori) to convert React components to SVG. The SVG is then converted to a PNG using [resvg-js](https://github.com/yisibl/resvg-js).
-
-> [!TIP]
-> Satori supports [a subset of CSS](https://github.com/vercel/satori?tab=readme-ov-file#css). Be sure to familiarize yourself with its limitations.
->
-> You can use the [Satori playground](https://og-playground.vercel.app/) to work on your images.
->
-> You can use Tailwind syntax with [tw-to-css](https://github.com/vinicoder/tw-to-css). An example is the [Tailwind preset](https://github.com/shepherdjerred/monorepo/blob/main/packages/astro-opengraph-images/src/presets/tailwind.tsx). You'll need to install this package yourself.
-
-## Presets
-
-Presets are located in [`src/presets/`](https://github.com/shepherdjerred/monorepo/tree/main/packages/astro-opengraph-images/src/presets). [Open a pull request](https://github.com/shepherdjerred/monorepo/compare) to contribute a preset you've created.
-
-Note: some presets use the [`tw-to-css`](https://github.com/vinicoder/tw-to-css) library. You'll need to install this dependency separately when using one of these presets. You'll see an error if the library is not already installed.
-
-```bash
-npm i tw-to-css
-```
-
-{{ range $preset := (ds "presets") -}}
-### `{{ strings.ReplaceAll ".png" "" $preset }}`
-
-```diff
-import opengraphImages, { presets } from "astro-opengraph-images";
-
-export default defineConfig({
-  integrations: [
-    opengraphImages({
-+      render: presets.{{ strings.ReplaceAll ".png" "" $preset }},
-    }),
-  ],
-});
-```
-
-![](assets/presets/{{ $preset }})
-
-{{ end }}
-
-## Alternatives
-
-Here are some similar libraries using Satori and Astro. I haven't done a feature comparison.
-
-- https://github.com/florian-lefebvre/satori-astro (This library looks excellent)
-- https://github.com/delucis/astro-og-canvas (Doesn't allow arbitrary layouts)
-- https://github.com/thewebforge/astro-og-images (Only allows you to choose from a list of templates)
-- https://github.com/tomaskebrle/astro-og-image (Seems limited)
-- https://github.com/cijiugechu/astro-satori (Possibly dead, hasn't been updated in a year)
-- https://github.com/kevinzunigacuellar/astro-satori (Possibly dead, hasn't been updated in a year)
-- https://github.com/rumaan/astro-vercel-og (Possibly dead, hasn't been updated in a year)