Skip to content

Create dynamic social share images using HTML + CSS via puppeteer 🎁

License

Notifications You must be signed in to change notification settings

chrisvxd/puppeteer-social-image

Repository files navigation

puppeteer-social-image

Build Status NPM JavaScript Style Guide

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

img

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.

basic template preview

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

article template preview

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

fiftyfifty template preview

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

About

Create dynamic social share images using HTML + CSS via puppeteer 🎁

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published