Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 29 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-11-06T22:40:46.325Z (about 1 month 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)
stars - puppeteer-social-image
stars - puppeteer-social-image

README

        # puppeteer-social-image

[![Build Status](https://travis-ci.com/chrisvxd/puppeteer-social-image.svg?branch=master)](https://travis-ci.com/chrisvxd/puppeteer-social-image) [![NPM](https://img.shields.io/npm/v/puppeteer-social-image.svg)](https://www.npmjs.com/package/puppeteer-social-image) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-prettier-brightgreen.svg)](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).

![img](https://i.ibb.co/PwVm1ky/Artboard.png)

## 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)