sodcalculator

10 Tech How-To

Social Card Image from URL with Headless Chrome

Guide 10-47069 · Updated · Step by step

This guide shows you how to generate a social card image (like an Open Graph image for Twitter or Facebook) from a URL using headless Chrome. You’ll create a screenshot of a webpage or a custom HTML template, which is perfect for auto-generating shareable images for blog posts, products, or any dynamic content. You’ll need a basic understanding of the command line and Node.js (or a similar environment) to follow along.

What You’ll Need

  • A computer with Chrome or Chromium installed (or the ability to install it).
  • Node.js and npm (if using the Node.js approach) or a scripting language like Python.
  • Access to a terminal or command prompt.
  • A URL to the webpage or HTML you want to capture (can be a local file or a remote URL).

Step-by-Step

  1. Install Headless Chrome: If you don’t have Chrome installed, download and install it. On most Linux systems, you can use sudo apt-get install chromium-browser or similar. On macOS, you can use Homebrew: brew install --cask google-chrome. For Windows, download the installer from the official site.
  2. Choose your method: You can use the command line directly, or write a script. For this guide, we’ll cover both the command-line and Node.js approaches.
  3. Command-line method (quick test): Open a terminal and run:
    chrome --headless --disable-gpu --screenshot=/path/to/output.png --window-size=1200,630 --hide-scrollbars https://example.com

    Replace chrome with the path to your Chrome executable (e.g., google-chrome on Linux, chrome on macOS). The --window-size sets the viewport size; 1200×630 is a common social card dimension. The output will be a PNG screenshot of the page.

  4. Node.js method (more control): Create a new directory and initialize npm: mkdir social-card && cd social-card && npm init -y.
  5. Install Puppeteer: Run npm install puppeteer. Puppeteer is a Node library that controls headless Chrome. It will download a compatible version of Chrome automatically.
  6. Write the script: Create a file named card.js with the following content:
    const puppeteer = require('puppeteer');
    
    (async () => {
      const browser = await puppeteer.launch();
      const page = await browser.newPage();
      await page.setViewport({ width: 1200, height: 630 });
      await page.goto('https://example.com', { waitUntil: 'networkidle0' });
      await page.screenshot({ path: 'card.png' });
      await browser.close();
    })();

    This script opens a page, sets the viewport, waits for the network to be idle, and takes a screenshot.

  7. Run the script: Execute node card.js. You should see a card.png file in the same directory.
  8. Customize the HTML: Instead of a live URL, you can create a local HTML file that uses your own design. For example, create template.html with your social card design (using CSS to style it). Then change the page.goto line to await page.goto('file://' + __dirname + '/template.html').
  9. Add dynamic content: To make the card dynamic (e.g., show a blog post title), you can pass variables to your HTML template. In Puppeteer, you can use page.setContent() to inject HTML with your data, or you can use a template engine like EJS. Here’s a simple example using setContent:
    const html = `<html><body><h1>${title}</h1></body></html>`;
    await page.setContent(html);

    Then take the screenshot.

  10. Automate for multiple URLs: Wrap the screenshot logic in a function that takes a URL and an output filename, and loop over an array of URLs. This allows you to generate cards in bulk.

Common Mistakes

  • Forgetting to set the viewport: If you don’t set the viewport, you’ll get a screenshot at the default size (usually 800×600), which won’t match the social card aspect ratio.
  • Not waiting for assets to load: If your page loads fonts, images, or scripts asynchronously, the screenshot may be taken before they appear. Use waitUntil: 'networkidle0' or a specific delay.
  • Using the wrong Chrome path: On some systems, the Chrome executable is not in the PATH. Use the full path or set the CHROME_PATH environment variable.
  • Forgetting to close the browser: If you don’t close the browser, the Node.js process may hang. Always call browser.close().
  • Not handling CORS or authentication: If your URL requires login or blocks headless browsers, you may get a blank or error page. You can pass cookies or use page.authenticate() for basic auth.

Tips

  • Use a consistent template: Create a reusable HTML template with placeholders for dynamic content. This ensures all your social cards look consistent.
  • Test with a real URL first: Before automating, test with a simple public URL to verify your setup works.
  • Optimize for performance: If you’re generating many cards, consider using a pool of browser instances or a single browser with multiple pages to speed things up.
  • Use PNG or JPEG: PNG is lossless and good for text, but JPEG is smaller. You can specify the format in page.screenshot() (e.g., type: 'jpeg', quality: 80).
  • Set a white background: Some pages have a transparent background; add a CSS rule to set a background color to avoid odd transparency in the output.

Troubleshooting

  • Blank or white screenshot: This often means the page didn’t load. Check the URL is correct and accessible. Try using waitUntil: 'load' instead of networkidle0. Also, ensure you’re not blocking JavaScript (headless Chrome runs JS by default).
  • Chrome not found: If you get an error like “Chrome executable not found”, install Chrome or specify the path in the executablePath option in Puppeteer: puppeteer.launch({ executablePath: '/usr/bin/chromium' }).
  • Screenshot is too small or large: Adjust the --window-size in the command line, or the setViewport call in Puppeteer. Remember that the viewport defines the visible area, not the full page height.
  • Fonts not rendering: If you use custom web fonts, they may not load in time. Use document.fonts.ready in your page or wait a bit longer. You can also embed fonts in the HTML using base64.
  • Images missing: If your card uses images from a CDN, they might be blocked by CORS or require authentication. Ensure the images are publicly accessible or use local files.
  • Script runs but no output: Check the file path in the screenshot call. If you’re using a relative path, it’s relative to the current working directory, not the script location. Use absolute paths or path.join(__dirname, 'output.png').

Frequently Asked Questions

Can I use this to generate Open Graph images for my website?

Yes, this is a common use case. You can run a script that generates an image for each new blog post or product, then reference that image in your HTML meta tags.

What is the best image size for social cards?

1200×630 pixels is the standard for Facebook and Twitter. LinkedIn uses 1200×627. It’s safe to use 1200×630.

Do I need to install Chrome separately if I use Puppeteer?

No, Puppeteer downloads a compatible version of Chromium automatically when you install it. However, you can override it with executablePath if you prefer to use your system Chrome.

Can I generate a card for a page that requires login?

Yes, you can pass cookies to Puppeteer using page.setCookie() or use page.authenticate() for basic HTTP auth. However, be careful with sensitive data.

How can I make the card text dynamic?

Use a template engine like EJS or Handlebars, or simply concatenate strings in your HTML before passing it to setContent. You can also use Puppeteer to fill in form fields on a page before taking a screenshot.

Can I generate cards in bulk?

Yes, write a loop that iterates over a list of URLs and calls your screenshot function for each. Use asynchronous code to run them in parallel for speed, but be mindful of memory usage.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →