npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

qmatias-next-api-og-image

v4.0.1

Published

Easy way to generate open-graph images dynamically using Next.js API Routes.

Downloads

9

Readme

Next.js API OG Image · version types license

Simple library with purpose of providing easy way to dynamically
generate open-graph images using Next.js API routes.

If you're not familiar with dynamic open-graph images concept - please see vercel/og-image repository's README for very detailed explaination.

you can treat this project as simpler and configurable version of mentioned earlier vercel repository

Features

  • [x] 🐄 Super easy usage
  • [x] 🌐 Suitable for serverless environment
  • [x] :bowtie: Elegant way for defining templates both in React and HTML
  • [x] 📬 Multiple strategies - pass values by GET and query params or POST and JSON body
  • [x] 🥷 TypeScript compatible

Installing

In your Next.js project, execute:

npm i next-api-og-image chrome-aws-lambda
# or
yarn add next-api-og-image chrome-aws-lambda

Short note about the peer dependencies

ℹ️ If your serverless function does not fit in the allowed size frames on Vercel (50MB), you may want to install older versions of chrome-aws-lambda

In order to do so, replace chrome-aws-lambda (while adding the dependencies) with [email protected] (47.6 MB)

Please, refer to https://github.com/neg4n/next-api-og-image/issues/23#issuecomment-1090319079 for more info 🙏

Examples

You can find more examples here:

the example/ directory contains simple Next.js application implementing next-api-og-image . To fully explore examples implemented in it by yourself - simply do npm link && cd example && npm i && npm run dev then navigate to http://localhost:3000/

Basic usage and explaination

HTML template
import { withOGImage } from 'next-api-og-image'

export default withOGImage({ template: { html: ({ myQueryParam }) => `<h1>${myQueryParam}</h1>` } })
React template
import { withOGImage } from 'next-api-og-image'

export default withOGImage({ template: { react: ({ myQueryParam }) => <h1>{myQueryParam}</h1> } })

Creating template

You've may noticed the html and react properties in configuration. Their responsibility is to provide HTML document to image creator (browser screenshot), filled with your values.

⚠️ NOTE
Template cannot be ambigious. You must either
define react or html. Never both at once

Specification

The html and react properties are template providers functions. Each function's first (and only) parameter is nothing else but HTTP request's query params converted to object notation.

This allows you to create fully customized HTML templates by simply accessing these parameters. The preferred way to do that is object destructuring.

⚠️ NOTE
html and react template provider functions
can be defined as asynchronous

Examples

HTML template
import { withOGImage } from 'next-api-og-image'

export default withOGImage({ template: { html: ({ myQueryParam }) => `<h1>${myQueryParam}</h1>` } })
React template
import { withOGImage } from 'next-api-og-image'

export default withOGImage({ template: { react: ({ myQueryParam }) => <h1>{myQueryParam}</h1> } })

if you send GET HTTP request to api route with code presented above e.g. localhost:3000/api/foo?myQueryParam=hello - it will render heading with content equal to 'hello'

Strategies

next-api-og-image allows you to choose strategy for providing values to the template. The available strategies are:

  1. query (default) - values are passed by query params and GET HTTP request.
    These values ⛔️ cannot be nested nor accessed by nested destructuring in template provider function.

  2. body - values are passed by POST HTTP request and JSON body.
    These values ✅ can be nested and accessed by nested destructuring in template provider function.

The strategies are determined by strategy prop in the configuration. Default strategy is query.

⚠️ NOTE
Regardless of the strategy - all properties (every single one)
are implicitly casted to string, even very long JSON's nested values

Types in template provider function

If you're using TypeScript, you probably want to have these things typed. Well... its actually super easy! Simply add generic types to withOGImage function.

  1. typed query strategy with query params ?foo=hello&bar=friend will look like this:
    export default withOGImage<'query', 'foo' | 'bar'>(/* ... */)
  2. typed body strategy with JSON payload { "foo": "hello", "imNested": { "bar": "friend" }} will look like this:
    export default withOGImage<'body', { foo: string, imNested: { bar: string } }>({ strategy: 'body', /* ... */ })

Errors

When strategy is set to query and you're sending POST HTTP request with JSON body or when strategy is set to body and you're sending GET HTTP request with query params - next-api-og-image will:

  1. Will throw an runtime error
  2. Set appropiate response message to the client You can disable this behaviour by setting dev: { errorsInResponse: false } in the configuration

Splitting files

Keeping all the templates inline within Next.js API route should not be problematic, but if you prefer keeping things in separate files you can follow the common pattern of creating files like my-template.html.js or my-template.js when you define template as react (naming convention is fully up to you) with code e.g.

export default function myTemplate({ myQueryParam }) {
  return `<h1>${myQueryParam}</h1>`
}

...or in TypeScript

import type { NextApiOgImageQuery } from 'next-api-og-image'

type QueryParams = 'myQueryParam'
export default function myTemplate({ myQueryParam }: Record<QueryParams, string>) {
  return `<h1>${myQueryParam}</h1>`
}

then importing it and embedding in the withOGImage.

Loading custom local fonts

In order to load custom fonts from the project source, you need to create source file with your font in base64 format or simply bind the font file content to the variable in your Next.js API route

Configuration

Apart from html and react configuration property (in template) (whose are required), you can specify additional info about how next-api-og-image should behave.

Example configuration with default values (apart from template.html or template.react prop):

const nextApiOgImageConfig = {
  // Values passing strategy
  strategy: 'query',
  // Response's 'Content-Type' HTTP header and browser screenshot type.
  type: 'png',
  // Screenshot's quality. WORKS ONLY IF 'type' IS SET TO 'jpeg'
  quality: 90,
  // Width of the image in pixels
  width: 1200,
  // Height of the image in pixels 
  height: 630,
  // 'Cache-Control' HTTP header
  cacheControl: 'max-age 3600, must-revalidate',
  // NOTE: Options within 'dev' object works only when process.env.NODE_ENV === 'development'
  dev: {
    // Whether to replace binary data (image/screenshot) with HTML
    // that can be debugged in Developer Tools
    inspectHtml: true,
    // Whether to set error message in response
    // if there are strategy related errors
    errorsInResponse: true,
  },
}

License

This project is licensed under the MIT license.
All contributions are welcome.