{"id":14962855,"url":"https://github.com/jerboa88/gatsby-plugin-component-to-image","last_synced_at":"2025-07-04T16:06:33.407Z","repository":{"id":243322595,"uuid":"804127661","full_name":"jerboa88/gatsby-plugin-component-to-image","owner":"jerboa88","description":"A Gatsby plugin to generate images and PDFs from React components","archived":false,"fork":false,"pushed_at":"2025-04-28T00:32:47.000Z","size":495,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-02T09:00:02.399Z","etag":null,"topics":["gatsby","gatsby-plugin","gatsbyjs","image-generation","image-processing","open-graph","open-graph-generator","open-graph-protocol","pdf","pdf-generation","react","react-components","reactjs","seo","seo-optimization","twitter-image"],"latest_commit_sha":null,"homepage":"https://johng.io/p/gatsby-plugin-component-to-image","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jerboa88.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2024-05-22T02:23:13.000Z","updated_at":"2025-04-28T00:32:50.000Z","dependencies_parsed_at":"2024-06-08T03:01:58.208Z","dependency_job_id":"7c3fdb00-6545-43cf-9e9e-71cdbc344b8f","html_url":"https://github.com/jerboa88/gatsby-plugin-component-to-image","commit_stats":null,"previous_names":["jerboa88/gatsby-plugin-component-to-image"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/jerboa88/gatsby-plugin-component-to-image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerboa88%2Fgatsby-plugin-component-to-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerboa88%2Fgatsby-plugin-component-to-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerboa88%2Fgatsby-plugin-component-to-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerboa88%2Fgatsby-plugin-component-to-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jerboa88","download_url":"https://codeload.github.com/jerboa88/gatsby-plugin-component-to-image/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jerboa88%2Fgatsby-plugin-component-to-image/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263573002,"owners_count":23482563,"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":["gatsby","gatsby-plugin","gatsbyjs","image-generation","image-processing","open-graph","open-graph-generator","open-graph-protocol","pdf","pdf-generation","react","react-components","reactjs","seo","seo-optimization","twitter-image"],"created_at":"2024-09-24T13:30:36.541Z","updated_at":"2025-07-04T16:06:33.400Z","avatar_url":"https://github.com/jerboa88.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Project Header --\u003e\n\u003cdiv align=\"center\"\u003e\n\u003cimg class=\"projectLogo\" src=\"icon.svg\" alt=\"Project logo\" title=\"Project logo\" width=\"256\"\u003e\n\n\u003ch1 class=\"projectName\"\u003eGatsby Plugin: Component to Image\u003c/h1\u003e\n\n\u003cp class=\"projectBadges\"\u003e\n\t\u003cimg src=\"https://johng.io/badges/category/Plugin.svg\" alt=\"Project category\" title=\"Project category\"\u003e\n\t\u003cimg src=\"https://img.shields.io/github/languages/top/jerboa88/gatsby-plugin-component-to-image.svg\" alt=\"Language\" title=\"Language\"\u003e\n\t\u003ca href=\"https://www.npmjs.com/package/gatsby-plugin-component-to-image\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/npm/v/gatsby-plugin-component-to-image\" alt=\"View package on npmjs\" title=\"View package on npmjs\"/\u003e\n\t\u003c/a\u003e\n\t\u003cimg src=\"https://img.shields.io/github/repo-size/jerboa88/gatsby-plugin-component-to-image.svg\" alt=\"Repository size\" title=\"Repository size\"\u003e\n\t\u003ca href=\"LICENSE\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/github/license/jerboa88/gatsby-plugin-component-to-image.svg\" alt=\"Project license\" title=\"Project license\"/\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp class=\"projectDesc\"\u003e\n\tA Gatsby plugin to generate images and PDFs from React components. Useful for dynamically generating Open Graph images, favicons, and more!\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\u003c/div\u003e\n\n\n## About\n\nThis plugin was inspired by similar plugins for generating [Open Graph] images like [gatsby-plugin-open-graph-images], [gatsby-plugin-satorare], and [gatsby-remark-twitter-cards], but is designed to easier to use and more customizable so that it can be used for more than just generating social images.\n\n### Features\n- **🚀 Works with any [React] component** : Generate images from any valid React component\n\t- Pass data to the component to customize the content, style, or layout of the generated images per page\n\t- Not limited by available plugin options like [gatsby-remark-twitter-cards]\n\t- Not limited by types of JSX elements or CSS properties supported by the plugin like [gatsby-plugin-satorare]\n- **📷 Configurable output filetypes**: Generate PNG, JPEG, or WebP images, as well as PDFs\n\t- Set the quality of the generated images\n\t- Optimize images for speed or file size\n- **📂 Customizable output paths**: Full control over paths of the generated pages and images\n\t- Set the path of the generated pages so that you can exclude them from your sitemap, or reuse them for other purposes\n\t- Save images to a separate directory\n- **🎛️ Default options**: Reuse the same options for multiple images\n\t- Set default options when adding the plugin to `gatsby-config.js`\n\t- Call the `setDefaultOptions()` function in `gatsby-node.js` to set them programmatically\n\n### Use cases\n- **🏞️ Social images**: Use your existing React components to generate Open Graph images and/or Twitter cards for your blog posts or other content\n- **🖼️ Favicons**: Dynamically generate favicons for your website\n- **📄 Documents**: Create PDF files for reports, invoices, resumes, or other documents\n\n### How it works\n1. When you call the `createImage()` function from `gatsby-node.js`, we save the options for that image/PDF and generate a regular [Gatsby] page from the component you provided.\n2. When the page is built, we use [Puppeteer] to render the page in a headless browser and, using the options you provided, either:\n   1. save a screenshot of the rendered component as an image, or\n   2. print the page to a PDF file\n\n\n## Installation\n1. Install the plugin with your favorite package manager:\n\n\t```sh\n\tnpm install jerboa88/gatsby-plugin-component-to-image\t\t# npm\n\t```\n\n\t```sh\n\tyarn add jerboa88/gatsby-plugin-component-to-image\t\t# yarn\n\t```\n\n\t```sh\n\tpnpm add jerboa88/gatsby-plugin-component-to-image\t\t# pnpm\n\t```\n\n\t```sh\n\tbun add github:jerboa88/gatsby-plugin-component-to-image\t# bun\n\t```\n\n2. Add the plugin to your `gatsby-config.js` file:\n\t```js\n\t// gatsby-config.js\n\n\tmodule.exports = {\n\t\tplugins: [\n\t\t\t'gatsby-plugin-component-to-image',\n\t\t],\n\t}\n\t```\n\n\tYou can also set default options for the plugin here:\n\t```js\n\t// gatsby-config.js\n\n\tmodule.exports = {\n\t\tplugins: [\n\t\t\t{\n\t\t\t\tresolve: 'gatsby-plugin-component-to-image',\n\t\t\t\toptions: {\n\t\t\t\t\ttype: 'jpeg',\n\t\t\t\t\tquality: 95,\n\t\t\t\t},\n\t\t\t},\n\t\t],\n\t}\n\t```\n\n\n## Usage\n\nThis plugin can be used for a variety of purposes, but we will show you how to use it to generate Open Graph images for your blog posts as an example:\n\n1. Create a component that renders the content you want to appear in the image:\n\t```tsx\n\t// src/templates/og-image/blog-post.tsx\n\n\timport React from 'react';\n\timport { graphql } from 'gatsby';\n\n\tconst BlogPostOGImage = ({ pageContext }) =\u003e {\n\t\t// Props passed to the createImage function with the `context` option\n\t\tconst { title, description, postDate } = pageContext;\n\t\t// Props automatically added by `gatsby-plugin-component-to-image`\n\t\tconst { size } = pageContext.imageMetadata;\n\n\t\t// Limit the size of the page to the size of the image\n\t\treturn (\n\t\t\t\u003cdiv style={{\n\t\t\t\tmaxWidth: size.width,\n\t\t\t\tmaxHeight: size.height,\n\t\t\t\tpadding: '1rem',\n\t\t\t\tbackgroundColor: 'white',\n\t\t\t\ttextAlign: 'center',\n\t\t\t}}\u003e\n\t\t\t\t\u003ch1\u003e{title}\u003c/h1\u003e\n\t\t\t\t\u003cp\u003e{description}\u003c/p\u003e\n\t\t\t\t\u003cp\u003ePublished on {postDate}\u003c/p\u003e\n\t\t\t\u003c/div\u003e\n\t\t);\n\t};\n\n\texport default BlogPostOGImage;\n\t```\n\n\tThe `pageContext` prop is passed to the component by Gatsby when the image is generated. It contains details about the generated image in `imageMetadata` that you can use to style your component, as well as any other data you passed to the `createImage()` function via the `context` prop.\n\n\tIn this example, we use the `size` property from `imageMetadata` to set the maximum width and height of the image, and we use the `title`, `description`, and `postDate` properties from `pageContext` to customize the content of the image for each blog post.\n\n2. Call the `createImage()` function from `gatsby-node.js` with your desired options:\n\t```js\n\t// gatsby-node.js\n\n\timport { resolve, join } from 'path';\n\timport { createImage } from 'gatsby-plugin-component-to-image';\n\n\texport const createPages = async ({ actions }) =\u003e {\n\t\t// Example blog post details. You could get this data from a CMS or other source\n\t\tconst blogPostDetails = {\n\t\t\ttitle: 'Blog Post 1',\n\t\t\tdescription: 'This is a blog post',\n\t\t\tpostDate: '2022-01-01',\n\t\t};\n\n\t\t// Generate an Open Graph image for the blog post. Pass the blog post details to the page template so that we can use them in the image\n\t\tconst imageMetadata = createImage({\n\t\t\tpagePath: join('/', '__generated', 'open-graph', 'blog-post-1'),\n\t\t\timagePath: join('/', 'images', 'open-graph', `blog-post-1.png`),\n\t\t\tcomponent: resolve('./src/templates/og-image/blog-post.tsx'),\n\t\t\tsize: {\n\t\t\t\twidth: 1200,\n\t\t\t\theight: 630,\n\t\t\t},\n\t\t\tcontext: blogPostDetails,\n\t\t});\n\n\t\t// Create a page for the blog post. Pass the image metadata to the page template so that we can use the image URL in our Open Graph meta tags\n\t\tactions.createPage({\n\t\t\tpath: join('/', 'blog', 'blog-post-1')\n\t\t\tcomponent: resolve('./src/templates/blog-post.tsx'),\n\t\t\tcontext: {\n\t\t\t\t...blogPostDetails,\n\t\t\t\timageMetadata: imageMetadata,\n\t\t\t}\n\t\t});\n\t};\n\t```\n\tThe function will return an object with the metadata for the image. If you don't specify certain options, the plugin will use default values which will be returned here.\n\n\tFor example, the metadata object can be used to:\n\t- pass the image URL to your page template so that you can use the image in your Open Graph meta tags, or\n\t- add nodes to the GraphQL schema so that you can query the image metadata in your components\n\n3. Run `gatsby build` to generate the image. The image will be saved to the path you specified with the `imagePath` option\n\n\n### Options\n\nIf you want to generate multiple images with the same options, you can set default options that will be reused every time you call `createImage()`.\n\nYou can either set default options for the plugin in `gatsby-config.js`:\n\n```js\n// gatsby-config.js\n\nmodule.exports = {\n\tplugins: [\n\t\t{\n\t\t\tresolve: 'gatsby-plugin-component-to-image',\n\t\t\toptions: {\n\t\t\t\ttype: 'webp',\n\t\t\t\tquality: 100,\n\t\t\t\tcontext: {\n\t\t\t\t\tsiteName: 'My Example Site',\n\t\t\t\t},\n\t\t\t\tverbose: true,\n\t\t\t},\n\t\t},\n\t],\n}\n```\n\nor call the `setDefaultOptions()` function in `gatsby-node.js`:\n\n```js\n// gatsby-node.js\n\nimport { setDefaultOptions } from 'gatsby-plugin-component-to-image';\n\nsetDefaultOptions({\n\ttype: 'webp',\n\tquality: 100,\n\tcontext: {\n\t\tsiteName: 'My Example Site',\n\t},\n\tverbose: true,\n});\n```\n\nMost of these options can also be set directly in the `createImage()` function. Doing this will override any default options you have set previously.\n\n\n#### Common Options\n\nThese options can either be set via the plugin options in `gatsby-config.js`, using the `setDefaultOptions()` function, or passed to the `createImage()` function.\n\n\u003e [!NOTE]\n\u003e `component` is a required option but it has no default value. Make sure to either set in the default options or pass it to the `createImage()` function.\n\n| **Option**         | **Description**                                                                                                                                                                           | **Type**     | **Default** |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |\n| `component`        | A path to the component used to generate the image.                                                                                                                                       | **required** |             |\n| `context`          | Additional context to pass to the image component. You can include any kind of data here that you want to include in your image so that you can access it later from the image component. | _optional_   | {}          |\n| `size.width`       | The width of the image in pixels. This value must be between 1 and 16383.                                                                                                                 | _optional_   | 1200        |\n| `size.height`      | The height of the image in pixels. This value must be between 1 and 16383.                                                                                                                | _optional_   | 630         |\n| `type`             | The file type of the image. This can be one of 'png', 'jpeg', 'webp', or 'pdf'.                                                                                                           | _optional_   | 'png'       |\n| `quality`          | The quality of the image. The has no effect on PNG images or PDFs. This value must be between 0 and 100.                                                                                  | _optional_   | undefined   |\n| `optimizeForSpeed` | Whether Puppeteer should optimize image encoding for speed instead of file size. This has no effect on PDFs.                                                                              | _optional_   | false       |\n\n\n#### Plugin Options\n\nThese options must either be set via the plugin options in `gatsby-config.js` or using the `setDefaultOptions()` function.\n\n\n| **Option** | **Description**                    | **Type**   | **Default** |\n| ---------- | ---------------------------------- | ---------- | ----------- |\n| `verbose`  | Whether to enable verbose logging. | _optional_ | false       |\n\n#### Job Options\n\nThese options must be passed to the `createImage()` function.\n\n| **Option**  | **Description**                                                                                                                                                                                                                 | **Type**     | **Default** |\n| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |\n| `pagePage`  | The destination path where the image component will be generated, relative to the `/public` directory. You may want to exclude this path from other plugins so that these components are not included in sitemaps, for example. | **required** |             |\n| `imagePath` | The destination path of the image itself, relative to the `/public` directory. This should include the file extension of the image.                                                                                             | **required** |             |\n\n\n## Contributing\nContributions, issues, and forks are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n\n## License\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details. This project includes various resources which carry their own copyright notices and license terms. See [LICENSE-THIRD-PARTY.md](LICENSE-THIRD-PARTY.md) for more details.\n\n\n[gatsby-plugin-open-graph-images]: https://github.com/squer-solutions/gatsby-plugin-open-graph-images/\n[gatsby-plugin-satorare]: https://github.com/okaryo/gatsby-plugin-satorare\n[gatsby-remark-twitter-cards]: https://github.com/alessbell/gatsby-remark-twitter-cards\n[Gatsby]: https://www.gatsbyjs.com/\n[Open Graph]: https://ogp.me/\n[Puppeteer]: https://pptr.dev/\n[React]: https://react.dev/\n[Typescript]: https://www.typescriptlang.org/\n[vercel/satori]: https://github.com/vercel/satori\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerboa88%2Fgatsby-plugin-component-to-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjerboa88%2Fgatsby-plugin-component-to-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerboa88%2Fgatsby-plugin-component-to-image/lists"}