Nonviolent Pirate Mobster

    bs-puppeteer-social-image

    0.8.6 • Public • Published

    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

    Keywords

    none

    Install

    npm i bs-puppeteer-social-image

    DownloadsWeekly Downloads

    2

    Version

    0.8.6

    License

    MIT

    Unpacked Size

    1.58 MB

    Total Files

    10

    Last publish

    Collaborators

    • zingzinco