{"id":13495304,"url":"https://github.com/frinyvonnick/node-html-to-image","last_synced_at":"2025-05-14T21:09:14.957Z","repository":{"id":36466914,"uuid":"226093388","full_name":"frinyvonnick/node-html-to-image","owner":"frinyvonnick","description":"A Node.js module that generates images from HTML","archived":false,"fork":false,"pushed_at":"2024-09-03T09:50:03.000Z","size":819,"stargazers_count":828,"open_issues_count":25,"forks_count":125,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-29T17:29:20.922Z","etag":null,"topics":["handlebars","html","html-to-image","image","javascript","nantes","node","pupeteer","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/node-html-to-image","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frinyvonnick.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["frinyvonnick"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2019-12-05T12:06:30.000Z","updated_at":"2024-10-28T16:33:58.000Z","dependencies_parsed_at":"2024-06-09T14:02:02.938Z","dependency_job_id":"032dee5d-a1da-427b-a6a8-d456301643bc","html_url":"https://github.com/frinyvonnick/node-html-to-image","commit_stats":{"total_commits":102,"total_committers":22,"mean_commits":4.636363636363637,"dds":"0.38235294117647056","last_synced_commit":"d51edae00fe11df2fd1b27ac4c940de5aae0d516"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frinyvonnick%2Fnode-html-to-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frinyvonnick%2Fnode-html-to-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frinyvonnick%2Fnode-html-to-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frinyvonnick%2Fnode-html-to-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frinyvonnick","download_url":"https://codeload.github.com/frinyvonnick/node-html-to-image/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247563913,"owners_count":20958971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["handlebars","html","html-to-image","image","javascript","nantes","node","pupeteer","typescript"],"created_at":"2024-07-31T19:01:33.362Z","updated_at":"2025-04-11T06:20:35.587Z","avatar_url":"https://github.com/frinyvonnick.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003eWelcome to node-html-to-image 🌄\u003c/h1\u003e\n\u003cp\u003e\n  \u003cimg alt=\"Version\" src=\"https://img.shields.io/badge/version-3.1.0-blue.svg?cacheSeconds=2592000\" /\u003e\n  \u003ca href=\"https://github.com/frinyvonnick/node-html-to-image#readme\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/documentation-yes-brightgreen.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/frinyvonnick/node-html-to-image/blob/master/LICENSE\" target=\"_blank\"\u003e\n    \u003cimg alt=\"License: Apache--2.0\" src=\"https://img.shields.io/badge/License-Apache--2.0-yellow.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/yvonnickfrin\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Twitter: yvonnickfrin\" src=\"https://img.shields.io/twitter/follow/yvonnickfrin.svg?style=social\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e A Node.js library that generates images from HTML\n\n### 🏠 [Homepage](https://github.com/frinyvonnick/node-html-to-image)\n\n\n## Description\n\nThis module exposes a function that generates images (png, jpeg) from HTML. It uses [puppeteer](https://github.com/puppeteer) in headless mode to achieve it. Additionally, it embarks [Handlebars](https://handlebarsjs.com/) to provide a way to add logic in your HTML.\n\n## Install\n\n```sh\nnpm install node-html-to-image\n# or\nyarn add node-html-to-image\n```\n\nNote: When you install Puppeteer, it downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. \n\n## Usage\n\n- [Simple example](#simple-example)\n- [TypeScript Support](#typescript-support)\n- [Options](#options)\n- [Setting output image resolution](#setting-output-image-resolution)\n- [Example with Handlebars](#example-with-handlebars)\n- [Using Handlebars helpers](#using-handlebars-helpers)\n- [Dealing with images](#dealing-with-images)\n- [Using the buffer instead of saving to disk](#using-the-buffer-instead-of-saving-to-disk)\n- [Generating multiple images](#generating-multiple-images)\n- [Using different puppeteer libraries](#using-different-puppeteer-libraries)\n\n### Simple example\n\n```js\nconst nodeHtmlToImage = require('node-html-to-image')\n\nnodeHtmlToImage({\n  output: './image.png',\n  html: '\u003chtml\u003e\u003cbody\u003eHello world!\u003c/body\u003e\u003c/html\u003e'\n})\n  .then(() =\u003e console.log('The image was created successfully!'))\n```\n\n### TypeScript support\n\nThe library is written in Typescript so it is available out of the box:\n\n```ts\nimport nodeHtmlToImage from 'node-html-to-image'\n```\n\n### Options\n\nList of all available options:\n\n| option            | description                                                                                                                                                                                                            | type                                            | required    |\n|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|-------------|\n| output            | The ouput path for generated image                                                                                                                                                                                     | string                                          | optional    |\n| html              | The html used to generate image content                                                                                                                                                                                | string                                          | required    |\n| type              | The type of the generated image                                                                                                                                                                                        | jpeg or png (default: png)                      | optional    |\n| quality           | The quality of the generated image (only applicable to jpg)                                                                                                                                                            | number (default: 80)                            | optional    |\n| content           | If provided html property is considered an handlebars template and use content value to fill it                                                                                                                        | object or Array                                 | optional    |\n| waitUntil         | Define when to consider markup succeded. [Learn more](https://github.com/puppeteer/puppeteer/blob/8370ec88ae94fa59d9e9dc0c154e48527d48c9fe/docs/api.md#pagesetcontenthtml-options).                                    | string or Array\u003cstring\u003e (default: networkidle0) | optional    |\n| puppeteer         | The puppeteer property let you use a different puppeteer library (like puppeteer-core or puppeteer-extra).                                                                                                             | object (default: puppeteer)                     | optional    |\n| puppeteerArgs     | The puppeteerArgs property let you pass down custom configuration to puppeteer. [Learn more](https://github.com/puppeteer/puppeteer/blob/8370ec88ae94fa59d9e9dc0c154e48527d48c9fe/docs/api.md#puppeteerlaunchoptions). | object                                          | optional    |\n| beforeScreenshot  | An async function that will execute just before screenshot is taken. Gives access to puppeteer page element.                                                                                                           | Function                                        | optional |\n| transparent       | The transparent property lets you generate images with transparent background (for png type).                                                                                                                          | boolean                                         | optional    |\n| encoding          | The encoding property of the image. Options are `binary` (default) or `base64`.                                                                                                                                        | string                                          | optional    |\n| selector          | The selector property lets you target a specific element to perform the screenshot on. (default `body`)                                                                                                                | string                                          | optional    |\n| handlebarsHelpers | The handlebarsHelpers property lets add custom logic to the templates using Handlebars sub-expressions. [Learn more](https://handlebarsjs.com/guide/builtin-helpers.html#sub-expressions).                             | object                                          | optional |\n| timeout           | Timeout for a [puppeteer-cluster](https://github.com/thomasdondorf/puppeteer-cluster#clusterlaunchoptions) (in `ms`). Defaults to `30000` (30 seconds).                                                                | number                                          | optional |\n\n\n### Setting output image resolution\n\n`node-html-to-image` takes a screenshot of the body tag's content. If you want to set output image's resolution you need to set its dimension using CSS like in the following example.\n\n```js\nconst nodeHtmlToImage = require('node-html-to-image')\n\nnodeHtmlToImage({\n  output: './image.png',\n  html: `\u003chtml\u003e\n    \u003chead\u003e\n      \u003cstyle\u003e\n        body {\n          width: 2480px;\n          height: 3508px;\n        }\n      \u003c/style\u003e\n    \u003c/head\u003e\n    \u003cbody\u003eHello world!\u003c/body\u003e\n  \u003c/html\u003e\n  `\n})\n  .then(() =\u003e console.log('The image was created successfully!'))\n```\n\n### Example with Handlebars\n\n[Handlerbars](https://handlebarsjs.com/) is a templating language. It generates HTML from a template and an input object. In the following example we provide a template to `node-html-to-image` and a content object to fill the template.\n\n```js\nconst nodeHtmlToImage = require('node-html-to-image')\n\nnodeHtmlToImage({\n  output: './image.png',\n  html: '\u003chtml\u003e\u003cbody\u003eHello {{name}}!\u003c/body\u003e\u003c/html\u003e',\n  content: { name: 'you' }\n})\n  .then(() =\u003e console.log('The image was created successfully!'))\n```\n\n[Handlebars](https://handlebarsjs.com/) provides a lot of expressions to handle common use cases like conditions or loops.\n\n\n### Using Handlebars helpers\n\n[Handlerbars sub-expressions](https://handlebarsjs.com/guide/builtin-helpers.html#sub-expressions) can be used to add custom logic to the templates. To do this, you must pass a `handlebarsHelpers` object with functions defined within.\n\nFor example, if you had a variable and wanted to do some conditional rendering depending on its value, you could do this:\n\n```js\nconst nodeHtmlToImage = require('node-html-to-image')\n\nnodeHtmlToImage({\n  output: './image.png',\n  content: { myVar: 'foo' },\n  handlebarsHelpers: {\n    equals: (a, b) =\u003e a === b,\n  },\n  html: `\n    \u003chtml\u003e\n      \u003cbody\u003e\n        {{#if (equals myVar 'foo')}}\u003cdiv\u003eFoo\u003c/div\u003e{{/if}}\n        {{#if (equals myVar 'bar')}}\u003cdiv\u003eBar\u003c/div\u003e{{/if}}\n      \u003c/body\u003e\n    \u003c/html\u003e`\n  \n})\n```\n\n### Dealing with images\n\nIf you want to display an image which is stored remotely do it as usual. In case your image is stored locally I recommend having your image in `base64`. Then you need to pass it to the template with the content property. Here is an example:\n\n```js\nconst nodeHtmlToImage = require('node-html-to-image')\nconst fs = require('fs');\n\nconst image = fs.readFileSync('./image.jpg');\nconst base64Image = new Buffer.from(image).toString('base64');\nconst dataURI = 'data:image/jpeg;base64,' + base64Image\n\nnodeHtmlToImage({\n  output: './image.png',\n  html: '\u003chtml\u003e\u003cbody\u003e\u003cimg src=\"{{{imageSource}}}\" /\u003e\u003c/body\u003e\u003c/html\u003e',\n  content: { imageSource: dataURI }\n})\n```\n### Dealing with fonts\nIf you want to apply fonts, you need to synchronize your parts loading of your website. One way doing it is to convert your font to base64 and add it to your style in your html. For example:\n```js\nconst font2base64 = require('node-font2base64')\n\nconst _data = font2base64.encodeToDataUrlSync('../my/awesome/font.ttf')\n\nconst html = `\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003cstyle\u003e\n      @font-face {\n        font-family: 'testFont';\n        src: url(\"{{{_data}}}\") format('woff2'); // don't forget the format!\n      }\n    \u003c/style\u003e\n  \u003c/head\u003e\n...\n``` \n\n### Using the buffer instead of saving to disk\n\nIf you don't want to save the image to disk and would rather do something with it immediately, you can use the returned value instead! The example below shows how you can generate an image and send it back to a client via using [express](https://github.com/expressjs/express).\n\n```js\nconst express = require('express');\nconst router = express.Router();\nconst nodeHtmlToImage = require('node-html-to-image');\n\nrouter.get(`/api/tweet/render`, async function(req, res) {\n  const image = await nodeHtmlToImage({\n    html: '\u003chtml\u003e\u003cbody\u003e\u003cdiv\u003eCheck out what I just did! #cool\u003c/div\u003e\u003c/body\u003e\u003c/html\u003e'\n  });\n  res.writeHead(200, { 'Content-Type': 'image/png' });\n  res.end(image, 'binary');\n});\n```\n\n### Generating multiple images\n\nIf you want to generate multiple images in one call you must provide an array to the content property. \n\n#### Saving to disk\n\nTo save on the disk you must provide the output property on each object in the content property.\n\n```js\nnodeHtmlToImage({\n  html: '\u003chtml\u003e\u003cbody\u003eHello {{name}}!\u003c/body\u003e\u003c/html\u003e',\n  content: [{ name: 'Pierre', output: './image1.png' }, { name: 'Paul', output: './image2.png' }, { name: 'Jacques', output: './image3.png' }]\n})\n  .then(() =\u003e console.log('The images were created successfully!'))\n```\n\n#### Using buffers\n\nIf you don't want to save the images to disk you can use the returned value instead. It returns an array of Buffer objects.\n\n```js\nconst images = await nodeHtmlToImage({\n  html: '\u003chtml\u003e\u003cbody\u003eHello {{name}}!\u003c/body\u003e\u003c/html\u003e',\n  content: [{ name: 'Pierre' }, { name: 'Paul' }, { name: 'Jacques' }]\n})\n```\n\n### Using different puppeteer libraries\n\nIf you want to use different puppeteer library you must provide the puppeteer property.\n\n```js\nconst chrome = require('chrome-aws-lambda');\nconst nodeHtmlToImage = require('node-html-to-image')\nconst puppeteerCore = require('puppeteer-core');\n\nconst image = await nodeHtmlToImage({\n  html: '\u003chtml\u003e\u003cbody\u003e\u003cdiv\u003eHello\u003c/div\u003e\u003c/body\u003e\u003c/html\u003e',\n  puppeteer: puppeteerCore,\n  puppeteerArgs: {\n      args: chromium.args,\n      executablePath: await chrome.executablePath,\n  }\n})\n```\n\n## Related\n\n### Libraries\n\n- [node-html-to-image-cli](https://github.com/frinyvonnick/node-html-to-image-cli) - CLI for this module\n\n### Articles \n\n- [Generate images from HTML in Node.js](https://yvonnickfrin.dev/node-html-to-image)\n- [node-html-to-image v1.2 is out 🎉](https://dev.to/yvonnickfrin/node-html-to-image-v1-2-is-out-42f4)\n\n## Run tests\n\n```sh\nyarn test\n```\n\n## Author\n\n👤 **FRIN Yvonnick \u003cfrin.yvonnick@gmail.com\u003e**\n\n* Website: [https://yvonnickfrin.dev](https://yvonnickfrin.dev)\n* Twitter: [@yvonnickfrin](https://twitter.com/yvonnickfrin)\n* Github: [@frinyvonnick](https://github.com/frinyvonnick)\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel free to check [issues page](https://github.com/frinyvonnick/node-html-to-image/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n## 📝 License\n\nCopyright © 2019 [FRIN Yvonnick \u003cfrin.yvonnick@gmail.com\u003e](https://github.com/frinyvonnick).\u003cbr /\u003e\nThis project is [Apache--2.0](https://github.com/frinyvonnick/node-html-to-image/blob/master/LICENSE) licensed.\n\n***\n_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_\n","funding_links":["https://github.com/sponsors/frinyvonnick"],"categories":["TypeScript","typescript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrinyvonnick%2Fnode-html-to-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrinyvonnick%2Fnode-html-to-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrinyvonnick%2Fnode-html-to-image/lists"}