puppeteer-social-image

Create dynamic social share images using HTML + CSS via puppeteer. For a hosted version, see OGIMPACT.

Installation

npm i puppeteer-social-image --save

Usage

Render "basic" template

import renderSocialImage from "puppeteer-social-image";

renderSocialImage({
  template: "basic",
  templateParams: {
    imageUrl:
      "https://images.unsplash.com/photo-1557958114-3d2440207108?w=1950&q=80",
    title: "Hello, world"
  },
  output: "image.png",
  size: "facebook"
});

Render custom template

import renderSocialImage from "puppeteer-social-image";

renderSocialImage({
  templateBody: '<div class="Main">Hello, {{name}}!</div>',
  templateStyles: ".Main { color: blue; }",
  templateParams: {
    name: "Jane"
  },
  output: "image.png",
  size: "facebook"
});

Render on a serverless function

Add the puppeteer-serverless package, and pass it to the render function via the browser option:

import puppeteer from "puppeteer-serverless";
import renderSocialImage from "puppeteer-social-image";

export default async () => {
  await renderSocialImage({
    template: "basic",
    templateParams: {
      imageUrl:
        "https://images.unsplash.com/photo-1557958114-3d2440207108?w=1950&q=80",
      title: "Hello, world"
    },
    browser: await puppeteer.launch({})
  });
};

API

renderSocialImage

Returns Promise<Buffer>.

Type: function (opts): Promise

• opts (object) Configuration options
• opts.template (string) Name of a prebuilt template. One of:
  • basic (default)
  • article
  • fiftyfifty
• opts.templateParams (object) Params to be passed to the template. If using prebuilt templates, see below for APIs.
• opts.templateBody (string?) Handlebars template to render in the body for a custom template. Populated with templateParams.
• opts.templateStyles (string?) CSS to use for a custom template. Passed to the head.
• opts.customTemplates (object?) Define multiple custom templates
  • opts.customTemplates[key] (string) Name for the customTemplate
  • opts.customTemplates[key].templateBody(string) Handlebars template to render in the body for this custom template. Populated with templateParams.
  • opts.customTemplates[key].templateStyles(string) CSS to use for this custom template. Passed to the head
• opts.output (string?) Path to write image
• opts.type (string?) Type of the output image. Overwritten by output path extension. One of:
  • jpeg (default)
  • png
• opts.jpegQuality (number, default 90) JPEG image quality
• opts.size (string?) Preset size for the image. One of:
  • facebook
  • twitter (default)
  • ig-landscape
  • ig-portrait
  • ig-square
  • ig-story
  • WIDTHxHEIGHT Any width, height pairing
• opts.browser (Browser?) Instance of puppeteer's Browser to use instead of the internal version. Useful for serverless functions, which may require chrome-aws-lambda. This browser instance will not be automatically closed.
• opts.preview (boolean?) Render the image with a chrome, as it would look on Twitter

Templates

basic

A basic template to show some short text overlaying an image.

API

• title (string) Title text for the image
• logo (string?) URL to a logo to render above the text
• imageUrl (string?) URL for the background image
• unsplashId (string?) Unsplash ID for the background image
• unsplashKeywords (string?) Unsplash keywords to use for the background image
• backgroundImageAnchor (string?, default "C") Anchor point for the background image. Valid options are C, N, NE, E, SE, S, SW, W or NW.
• backgroundImageOverlay (boolean?, default true) Add a dark overlay on top of the background image
• background (string?) CSS background prop. Prefer imageUrl if using image.
• color (string?, default "white") Color for the title
• googleFont (string?) Name for Google font to load
• fontFamily (string?, default '"Lato", "Helvetica Neue", sans-serif') Font family
• fontSize (string?, default "128px") Font size
• watermark (string?) Watermark text to render at the bottom of the image.

article

A template for an article, with an eyebrow that can be used for dates

API

• title (string) Title text
• subtitle (string?) Subtitle text
• eyebrow (string) Eyebrow text, rendered above the title, like a date
• logo (string?) URL to a logo to render above the text
• imageUrl (string?) URL for the background image
• unsplashId (string?) Unsplash ID for the background image
• unsplashKeywords (string?) Unsplash keywords to use for the background image
• backgroundImageAnchor (string?, default "C") Anchor point for the background image. Valid options are C, N, NE, E, SE, S, SW, W or NW.
• backgroundImageOverlay (boolean?, default true) Add a dark overlay on top of the background image
• background (string?) CSS background prop. Prefer imageUrl if using image.
• color (string?, default "white") Color for the text
• googleFont (string?) Name for Google font to load
• fontFamily (string?, default '"Lato", "Helvetica Neue", sans-serif') Font family
• watermark (string?) Watermark text to render at the bottom of the image.

fiftyfifty

A multiuse template for an array of content

API

• title (string) Title text
• subtitle (string?) Subtitle text
• footer (string) Footer text
• split (straight | diagonal | diagonal-reverse, default straight) Style of split between content and image
• logo (string?) URL for the logo image
• imageUrl (string?) URL for the background image
• unsplashId (string?) Unsplash ID for the background image
• unsplashKeywords (string?) Unsplash keywords to use for the background image
• googleFont (string?) Name for Google font to load
• fontFamily (string?, default '"Lato", "Helvetica Neue", sans-serif') Font family
• watermark (string?) Watermark text to render in the bottom left. Same as footer.

License

MIT © Chris Villa