How do I use O.G. image?

1. For the app you want to generate og:image previews for, make a page that contains the preview data. For instance, O.G. image itself has an example preview of its own og:image at /preview/logo. It should contain only what you want to appear in the og:image, in a roughly 1200x675 pixel window. O.G. image will open this page in a headless browser and screenshot it.
2. Fork O.G. image and modify knownSites.ts to include your site. The KnownSites object in that file contains a list of sites by name, then by environment. You should set the scaleFactor to 1 at first, and read the Vercel documentation on the Cache-Control header to set the value of cacheControl. Here's an example KnownSites object:

   
   const oneWeekInSecs = 60 * 60 * 24 * 7;
   const KnownSites: KnownSitesType = {
     exampleSite: {
       production: {
         baseUri: "https://www.example.com",
         scaleFactor: 1,
         cacheControl: "s-maxage=${oneWeekInSecs}, immutable, public",
       },
       staging: {
         baseUri: "https://staging.example.com",
         scaleFactor: 1,
         cacheControl: "s-maxage=${oneWeekInSecs}, immutable, public",
       },
     },
   }
   

3. Deploy your O.G. image fork to Vercel. Make note of the URL that it is deployed to, e.g. https://ogimageexample.youraccount.vercel.app. You can also deploy to a custom domain.
4. On the app you want to generate og:image preview for, set its og:image to something like this: https://ogimageexample.youraccount.vercel.app/api/ogImage/exampleSite/production/path/to/your/preview/endpoint

   O.G. image URI	API subpath	Site name	Environment	urlSubPath
   https://ogimageexample.youraccount.vercel.app	/api/ogImage	/exampleSite	/production	/path/to/your/preview/endpoint

Examples

• For example, as mentioned above, O.G. image itself has a page for its own preview at /preview/logo. That link is a page containing a regular React component. It also knows about itself in KnownSites, with a site name of og and an environment called production. Thus, it can generate an og:image for itself by going to https://ogimage.micahrl.com/api/ogImage/og/production/preview/logo.

  O.G. image URI	API subpath	Site name	Environment	urlSubPath
  https://ogimage.micahrl.com	/api/ogImage	/og	/production	/preview/logo

• For a more complicated example, see my app biblemunger. It has a page with a dynamic route that renders a single munged verse (meaning, a single verse with a text replacement applied). For example, here is one of my favorites. That URL is intended for users, and has buttons, a page header, etc. Biblemunger also has a preview page with a dynamic route that renders just the munged verse, without buttons or page header; the preview page for the above example is here. Since biblemunger is known to O.G. image, it can set an og:image tag to https://ogimage.micahrl.com/api/ogImage/biblemunger/production/preview/munge/wine/whiteclaws/49-5-18, which looks like this in tabular form:

  O.G. image URI	API subpath	Site name	Environment	urlSubPath
  https://ogimage.micahrl.com	/api/ogImage	/biblemunger	/production	/preview/munge/wine/whiteclaws/49-5-18

Beware

Do note that Vercel doesn't recommend using puppeteer on its serverless Functions platform, and O.G. image uses puppeteer to start a Chromium process to take the screenshot.

(That said, they do have an example that uses puppeteer to generate og:image previews from text.)

One reason for this is that AWS Lambda functions, on which Vercel Functions are built, have a 50MB maximum code size. If puppeteer + chrome-aws-lambda + my O.G. image code exceed that maximum, deploying to Vercel will fail with an error like Error: Required lambda files exceed max lambda size of 50000000 bytes. If this happens to you, Vercel will likely just tell you not to do this.