Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chrisvxd/puppeteer-social-image
Create dynamic social share images using HTML + CSS via puppeteer 🎁
https://github.com/chrisvxd/puppeteer-social-image
facebook opengraph puppeteer twitter
Last synced: 9 days ago
JSON representation
Create dynamic social share images using HTML + CSS via puppeteer 🎁
- Host: GitHub
- URL: https://github.com/chrisvxd/puppeteer-social-image
- Owner: chrisvxd
- License: mit
- Created: 2019-05-13T13:38:32.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T21:45:50.000Z (almost 2 years ago)
- Last Synced: 2024-10-27T09:16:46.170Z (12 days ago)
- Topics: facebook, opengraph, puppeteer, twitter
- Language: JavaScript
- Homepage:
- Size: 33.6 MB
- Stars: 219
- Watchers: 7
- Forks: 28
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-puppeteer - puppeteer-social-image - Render social share images using HTML + CSS. (Packages)
README
# puppeteer-social-image
[](https://travis-ci.com/chrisvxd/puppeteer-social-image) [](https://www.npmjs.com/package/puppeteer-social-image) [](https://prettier.io)
Create dynamic social share images using HTML + CSS via puppeteer. For a hosted version, see [OGIMPACT](https://github.com/chrisvxd/og-impact).
## Installation
```sh
npm i puppeteer-social-image --save
```
## Usage
### Render "basic" template
```js
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
```js
import renderSocialImage from "puppeteer-social-image";
renderSocialImage({
templateBody: '
Hello, {{name}}!',
templateStyles: ".Main { color: blue; }",
templateParams: {
name: "Jane"
},
output: "image.png",
size: "facebook"
});
```
### Render on a serverless function
Add the [`puppeteer-serverless` package](https://github.com/saasify-sh/puppeteer-serverless), and pass it to the render function via the `browser` option:
```js
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`.
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`](https://www.npmjs.com/package/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](http://www.chrisvilla.co.uk)