Awesome
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 optionsopts.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 templatesopts.customTemplates[key]
(string) Name for the customTemplateopts.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 imageopts.type
(string?) Type of the output image. Overwritten by output path extension. One of:jpeg
(default)png
opts.jpegQuality
(number, default90
) JPEG image qualityopts.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'sBrowser
to use instead of the internal version. Useful for serverless functions, which may requirechrome-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.
<img width="400" alt="basic template preview" src="https://ogi.sh/preview?title=Hello%20World&ghBust=1" />API
title
(string) Title text for the imagelogo
(string?) URL to a logo to render above the textimageUrl
(string?) URL for the background imageunsplashId
(string?) Unsplash ID for the background imageunsplashKeywords
(string?) Unsplash keywords to use for the background imagebackgroundImageAnchor
(string?, default"C"
) Anchor point for the background image. Valid options areC
,N
,NE
,E
,SE
,S
,SW
,W
orNW
.backgroundImageOverlay
(boolean?, defaulttrue
) Add a dark overlay on top of the background imagebackground
(string?) CSS background prop. PreferimageUrl
if using image.color
(string?, default"white"
) Color for the titlegoogleFont
(string?) Name for Google font to loadfontFamily
(string?, default'"Lato", "Helvetica Neue", sans-serif'
) Font familyfontSize
(string?, default"128px"
) Font sizewatermark
(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
<img width="400" alt="article template preview" src="https://ogi.sh/preview?template=article&eyebrow=27%20AUGUST&title=INTO%20THE%20OCEAN&subtitle=Explore%20the%20depths%20of%20the%20deep%20blue%20sea&unsplashId=gGX1fJkmw3k&ghBust=1" />API
title
(string) Title textsubtitle
(string?) Subtitle texteyebrow
(string) Eyebrow text, rendered above the title, like a datelogo
(string?) URL to a logo to render above the textimageUrl
(string?) URL for the background imageunsplashId
(string?) Unsplash ID for the background imageunsplashKeywords
(string?) Unsplash keywords to use for the background imagebackgroundImageAnchor
(string?, default"C"
) Anchor point for the background image. Valid options areC
,N
,NE
,E
,SE
,S
,SW
,W
orNW
.backgroundImageOverlay
(boolean?, defaulttrue
) Add a dark overlay on top of the background imagebackground
(string?) CSS background prop. PreferimageUrl
if using image.color
(string?, default"white"
) Color for the textgoogleFont
(string?) Name for Google font to loadfontFamily
(string?, default'"Lato", "Helvetica Neue", sans-serif'
) Font familywatermark
(string?) Watermark text to render at the bottom of the image.
fiftyfifty
A multiuse template for an array of content
<img width="400" src="https://ogi.sh/preview?template=fiftyfifty&title=What%20NOT%20to%20do%20when%20remote%20working&subtitle=Lorem%20ipsum%20dolor%20sit%20amet%2C%20consectetur%20adipiscing%20elit%2C%20sed%20do%20eiusmod%20tempor%20incididunt%20ut%20labore%20et%20dolore%20magna%20aliqua.%20Test%20and%20test%20some%20more.&unsplashId=QLqNalPe0RA&split=diagonal&logo=data%3Aimage%2Fsvg%2Bxml%3Bcharset%3Dutf-8%3Bbase64%2CPHN2ZyB3aWR0aD0nMjA5NicgaGVpZ2h0PSc0NDAnIHhtbG5zPSdodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2Zyc%2BPGcgZmlsbD0nbm9uZScgZmlsbC1ydWxlPSdldmVub2RkJz48cmVjdCBmaWxsPScjRkZFNjAwJyB3aWR0aD0nNDQwJyBoZWlnaHQ9JzQ0MCcgcng9JzUyJy8%2BPGcgdHJhbnNmb3JtPSd0cmFuc2xhdGUoODYgMTQyKSc%2BPHBhdGggZD0nTTE3Ni4xMzkgOTcuMTVsLTE2LjA5MSA1Mi45MDNTMTU4Ljg2NCAxNTUgMTUzLjY1NSAxNTVoLTE5Ljg4N2MtNi4xNTUgMC03LjU3Ni01LjQxOC03LjU3Ni01LjQxOGwtMjMuNjc1LTc1LjE0NC0yMy42NzUgNzUuMTQ0Uzc3LjQyMiAxNTUgNzEuMjY2IDE1NUg1MC40M2MtNS4yMDggMC02LjM5Mi00Ljk0Ny02LjM5Mi00Ljk0N0wuMjQgNi44MzFDLS40NyA0LjAwNS4yNCAwIDQuNTAyIDBoMjYuMDQzYzcuMTAzIDAgOC41MjMgNC43MTEgOS40NyA3LjUzOGwyMy40MzkgODAuMDkxTDg2LjE4IDcuNTM4Qzg3LjEyOCA0LjI0IDg4Ljc4NSAwIDk0LjIzMSAwaDE2LjU3MmM1LjIwOSAwIDYuODY2IDQuMjQgNy44MTMgNy41MzhsMjIuOTY1IDgwLjA5MSAyMy40MzgtODAuMDkxYy42Mi0yLjQ2NyAxLjk2Mi02LjM3IDcuMDE1LTcuMzIzLjY1LS4xNDIgMS40LS4yMTUgMi4yNjUtLjIxNWg0Ny40NDlDMjU4LjAyIDAgMjc3IDE5LjcyNCAyNzcgNDguNjhjMCAyOS4xNjUtMTkuNDAxIDQ4LjQ3LTU1LjQ2MyA0OC40N0gxNzYuMTR6bTQ0LjcyLTMwLjY0NWMxNS4zNzIgMCAyMi4wNzMtOC40MzEgMjIuMDczLTE4LjIzNSAwLTEwLjE5Ny02LjctMTguNDMyLTIyLjA3Mi0xOC40MzJoLTIzLjQ0M2wtMTEuMTcyIDM2LjY2N2gzNC42MTV6JyBmaWxsLW9wYWNpdHk9Jy44NycgZmlsbD0nIzAwMCcvPjxjaXJjbGUgZmlsbD0nIzIxMUQwMCcgY3g9JzI2MycgY3k9JzE0MScgcj0nMTQnLz48L2c%2BPHRleHQgZm9udC1mYW1pbHk9J0F2ZW5pck5leHQtRGVtaUJvbGQsIEF2ZW5pciBOZXh0JyBmb250LXNpemU9JzIxMCcgZm9udC13ZWlnaHQ9JzUwMCcgbGV0dGVyLXNwYWNpbmc9JzE3LjIxMycgZmlsbD0nIzIxMUQwMCc%2BPHRzcGFuIHg9JzU2MCcgeT0nMjk3Jz5XRUxMUEFJRC5JTzwvdHNwYW4%2BPC90ZXh0PjwvZz48L3N2Zz4%3D&ghBust=1" alt="fiftyfifty template preview" />API
title
(string) Title textsubtitle
(string?) Subtitle textfooter
(string) Footer textsplit
(straight
|diagonal
|diagonal-reverse
, defaultstraight
) Style of split between content and imagelogo
(string?) URL for the logo imageimageUrl
(string?) URL for the background imageunsplashId
(string?) Unsplash ID for the background imageunsplashKeywords
(string?) Unsplash keywords to use for the background imagegoogleFont
(string?) Name for Google font to loadfontFamily
(string?, default'"Lato", "Helvetica Neue", sans-serif'
) Font familywatermark
(string?) Watermark text to render in the bottom left. Same asfooter
.
License
MIT © Chris Villa