Core Concept

NextJS comes with an ImageResponse class that allows you to dynamically create images.
The image response is designed to be returned on its own as http response containing an image payload.
You can generate this image using JSX.

Simple Demo

In the below example we create a simple HTTP endpoint that generates an image on the fly.

Note: You can even use the API endpoint as the src for an img element to display it in your application as we have done.

app/api/route.tsx

app/page.tsx

import { ImageResponse } from "next/og";

export async function GET() {
  return new ImageResponse(
    (
      <div
        style={{
          /** Take up all the space from the parent */
          height: "100%",
          width: "100%",

          /** Center the children */
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        <div style={{ fontSize: "36px" }}>Sample Image</div>
      </div>
    ),
    {
      width: 300,
      height: 300,
    }
  );
}

What is Satori?

Note that ImageResponse is not a complete browser implementation of html and css and is instead a stripped down engine inspired by react native. The engine is called satori and is free and open source on GitHub. It calls itself "Enlightened library to convert HTML and CSS to SVG"

This shouldn’t mean much in terms of feature availability (other than you need to use the style attribute). But it is something to be aware of in case you run into issues.

Custom Components

As a matter of fact the course completion certificates at BooleanArt are generated on the fly using ImageResponse. It is helpful to create utility components to make it easier to build advanced layouts.

The following example demonstrates some of the custom components we used at BooleanArt.

lib/ImageResponseComponents.tsx

app/api/route.tsx

app/page.tsx

export const ImageResponseRoot = ({ children }: React.PropsWithChildren) => {
  return (
    <div
      style={{
        /** Take up all the space from the parent */
        height: "100%",
        width: "100%",
        /** Setup a column layout */
        display: "flex",
        flexDirection: "column",
        /** Allow children to position themselves relatively */
        position: "relative",
      }}
    >
      {children}
    </div>
  );
};

export const ImageResponseFullBackgroundImg = ({ src }: { src: string }) => {
  return (
    <img
      style={{
        position: "absolute",
        top: "0px",
        bottom: "0px",
        left: "0px",
        right: "0px",
      }}
      src={src}
    />
  );
};

export const ImageResponseCenteredText = ({
  children,
}: React.PropsWithChildren) => {
  return (
    <div
      style={{
        display: "flex",
        flex: 1,
        justifyContent: "center",
        alignItems: "center",
      }}
    >
      {children}
    </div>
  );
};

import path from "path";
import { promises as fs } from "fs";
export async function localImageToSrc(localPath: string): Promise<string> {
  const imageBuffer = await fs.readFile(path.resolve(localPath));
  const base64ImageSrc = `data:image/png;base64,${imageBuffer.toString(
    "base64"
  )}`;
  return base64ImageSrc;
}

Using Custom Fonts

The Image response class allows you to pass in a set of custom fonts which enables expressive typography.

In the following example we use a custom loader to make it easier to load custom fonts and then use that font for a generated image.

lib/ImageResponseFonts.ts

app/api/route.tsx

app/page.tsx

import { promises as fs } from "fs";
import path from "path";

import type { ImageResponse } from "next/og";
type FontOptions = NonNullable<
  NonNullable<
    ConstructorParameters<typeof ImageResponse>[1]
  >["fonts"]
>[number];

export const fontGagalin = "Gagalin";

export const getFontGagalin = async (): Promise<FontOptions> => {
  const data = await fs.readFile(path.resolve("./public/fonts/Gagalin.otf"));
  return {
    name: fontGagalin,
    data: data,
  };
};

Passing Parameters to NextJS API Endpoints

In order to provide custom content for your generated Image you can pass in parameters to your api route.

The following example demonstrates using searchParams for an HTTP GET handler.

app/api/route.tsx

app/page.tsx

import {
  ImageResponseCenteredText,
  ImageResponseFullBackgroundImg,
  ImageResponseRoot,
  localImageToSrc,
} from "@/lib/ImageResponseComponents";
import { ImageResponse } from "next/og";
import { fontGagalin, getFontGagalin } from "@/lib/ImageResponseFonts";
import { NextRequest } from "next/server";

export async function GET(req: NextRequest) {
  const message = new URL(req.url).searchParams.get("message") ?? "NO MESSAGE";

  return new ImageResponse(
    (
      <ImageResponseRoot>
        <ImageResponseFullBackgroundImg
          src={await localImageToSrc("./public/images/background.png")}
        />
        <ImageResponseCenteredText>
          <div style={{ fontSize: "69px", fontFamily: fontGagalin }}>
            {message}
          </div>
        </ImageResponseCenteredText>
      </ImageResponseRoot>
    ),
    {
      width: 1080,
      height: 1080,
      fonts: [await getFontGagalin()],
    }
  );
}

Debugging ImageResponse Issues

A simple way to debug layout issues with ImageResponse is to pass in true for the debug property.

This is demonstrated in the below example.

app/api/route.tsx

app/page.tsx

import {
  ImageResponseCenteredText,
  ImageResponseFullBackgroundImg,
  ImageResponseRoot,
  localImageToSrc,
} from "@/lib/ImageResponseComponents";
import { ImageResponse } from "next/og";
import { fontGagalin, getFontGagalin } from "@/lib/ImageResponseFonts";
import { NextRequest } from "next/server";

export async function GET(req: NextRequest) {
  const message = new URL(req.url).searchParams.get("message") ?? "NO MESSAGE";

  return new ImageResponse(
    (
      <ImageResponseRoot>
        <ImageResponseFullBackgroundImg
          src={await localImageToSrc("./public/images/background.png")}
        />
        <ImageResponseCenteredText>
          <div style={{ fontSize: "69px", fontFamily: fontGagalin }}>
            {message}
          </div>
        </ImageResponseCenteredText>
      </ImageResponseRoot>
    ),
    {
      width: 1080,
      height: 1080,
      fonts: [await getFontGagalin()],
      debug: true,
    }
  );
}

Note that if you are still struggling to debug issues, you can add a thicker border manually around the element that is giving you issues.

Transcript