DEV Community

Ondrej Machala
Ondrej Machala

Posted on

Your README Screenshots Are From 3 Versions Ago

#github #opensource #documentation #automation

I was evaluating an open source library last week. The README had four screenshots showing the UI. The actual UI looked completely different. Different layout, different colors, different sidebar.

I almost closed the tab because I thought I was looking at the wrong project.

This is incredibly common. Open source maintainers take README screenshots once, when they're excited about the project. Then never again. Because updating them means:

  1. Run the app locally
  2. Get it into the right state
  3. Take screenshots
  4. Crop and resize
  5. Commit the new images
  6. Hope the markdown paths still work

Automate it

Define your README screenshots in config:

{
  "screenshots": [
    {
      "name": "dashboard",
      "url": "http://localhost:3000/dashboard",
      "selector": ".main-content"
    },
    {
      "name": "settings",
      "url": "http://localhost:3000/settings",
      "selector": ".settings-form",
      "viewports": ["desktop", "mobile"]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Update them:

npx heroshot
Enter fullscreen mode Exit fullscreen mode

Generate the markdown

Instead of writing image tags manually, use the snippet command:

npx heroshot snippet
Enter fullscreen mode Exit fullscreen mode

This outputs <picture> elements with dark mode support:

<picture>
  <source srcset="./heroshots/dashboard-dark.png" media="(prefers-color-scheme: dark)">
  <img src="./heroshots/dashboard-light.png" alt="Dashboard">
</picture>
Enter fullscreen mode Exit fullscreen mode

Paste that into your README. GitHub renders it correctly, and users see screenshots matching their system theme.

In CI

Add a GitHub Action that updates screenshots on release:

name: Update README screenshots
on:
  release:
    types: [published]

jobs:
  screenshots:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          lfs: true
      - name: Start app
        run: npm start &
      - name: Wait for app
        run: npx wait-on http://localhost:3000
      - name: Capture screenshots
        run: npx heroshot
      - name: Commit if changed
        run: |
          git add heroshots/
          git diff --staged --quiet || git commit -m "update screenshots"
          git push
Enter fullscreen mode Exit fullscreen mode

Now every release automatically updates the README screenshots. They never fall 3 versions behind again.

The cost of stale screenshots

People judge open source projects in seconds. If the README screenshots don't match the actual product, visitors assume the project is abandoned or poorly maintained. You might have shipped 50 improvements since that screenshot. Nobody can tell.

Fresh screenshots signal an active, maintained project. Heroshot keeps them that way.

Top comments (0)