kktsvetkov /
js-social-preview
Tiny JS tool to dynamically create previews for social sharing
Active repository
JavaScriptMIT#facebook#fb#javascript#js
⑂ 1 forks◯ 1 issuesUpdated Aug 19, 2025
Loading repository data…
chrisvxd / repository
puppeteer-social-image
Create dynamic social share images using HTML + CSS via puppeteer 🎁
#facebook#opengraph#puppeteer#twitter
Live repository statistics
★ 219Stars
⑂ 26Forks
◯ 18Open issues
◉ 219Watchers
README preview
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)articlefiftyfifty
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:facebooktwitter(default)ig-landscapeig-portraitig-squareig-storyWIDTHxHEIGHTAny width, height pairing
opts.browser(Browser?) Instance of puppeteer'sBrowserto 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.
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,WorNW.backgroundImageOverlay(boolean?, defaulttrue) Add a dark overlay on top of the background imagebackground(string?) CSS background prop. PreferimageUrlif 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
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,WorNW.backgroundImageOverlay(boolean?, defaulttrue) Add a dark overlay on top of the background imagebackground(string?) CSS background prop. PreferimageUrlif 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
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
ALGORITHMICALLY RELATED
Similar Open-Source Projects
Selected from shared topics, language and repository description—not editorial ratings.
★ 2