Social Media Image Kit Laravel Package

Getting Started

This is a Statamic addon (v1.4.0 supports Statamic 3.x–6.x), so install it into an existing Statamic site rather than a bare Laravel app:

composer require stillat/social-media-image-kit
php artisan vendor:publish --tag=social-media-image-kit-config

Look at these first, in order:

1. config/social-media-image-kit.php — template name, route/URL prefix, image dimensions, and any driver/browser settings. This is the single place that determines what URL you will be embedding in your <head>.
2. resources/views/social-media-image.antlers.html (or whichever template the config points to) — the Antlers view that is rendered to a PNG/JPEG. Everything visual (background, logo, title, tagline) lives here, not in PHP.
3. routes/ in the addon — confirm the URL pattern the addon registers, since you will hard-code it into your layout.

The first useful thing to build is a single OG image for a blog/news collection:

{{# resources/views/layout.antlers.html #}}
<meta property="og:image" content="{{ social_media_image url }}?id={{ id }}&v={{ last_modified }}">
<meta name="twitter:card" content="summary_large_image">

Then visit the generated URL directly in the browser. If the template renders as HTML for a moment before the image is produced, that is expected on a cold cache — the addon renders the Antlers template, screenshots it, and stores the result. Once you have one entry working, add the field to the blueprint or template loop and move on to the patterns below.

Implementation Patterns

Template-per-context. Keep a base Antlers template and use Statamic's view resolution (or a template variable in the config / query string, depending on your version) to render a different layout per collection — e.g. social/blog, social/product, social/event. This keeps typography and brand assets consistent while letting each content type show the right fields.

Augmented entry data (new in 1.4.0). The headline change is that the template now receives an augmented entry, which means relationship fields and tag-driven data resolve properly inside the image template. Practical consequences:

• {{ author:name }}, {{ hero_image:url }}, {{ categories }}{{ title }}{{ /categories }} now work without manually reaching into the entry's raw data or writing a custom tag.
• Tag pairs and conditionals that depend on relations (e.g. showing a "Sponsored" ribbon when a sponsor relationship is set) can be authored directly in the image template.
• A common pattern: render the primary category or first tag as a small pill in the bottom-left corner:

{{ if tags }}
  <div class="pill">{{ tags limit="1" }}{{ title }}{{ /tags }}</div>
{{ /if }}

Because augmentation is now happening, be deliberate about it — see the gotchas on performance.

Recreate from the Control Panel (new in 1.4.0). The CP action lets editors regenerate an image without touching the CLI. This is most useful in two scenarios:

• Editors changed a title or hero image and want the share card refreshed immediately (e.g. before pushing a campaign live).
• A template/layout change shipped and you want to refresh selected entries rather than the whole site.

Pair it with sensible cache-busting in the layout (?v={{ last_modified }}) so the new file is actually picked up by social scrapers.

Regenerate on save. For a hands-off workflow, hook into the entry saved event and clear/regenerate the cached image. Combined with the CP action, this gives you "automatic by default, manual override when needed."

Warm the cache on publish. Generated images are the slowest part of the request. For scheduled posts or imports, dispatch a job that requests the image URL (or calls the addon's generation routine) at publish time rather than letting the first social scraper eat the cold-start cost.

Shared meta partial. Put the og:image / twitter:image tags in one Antlers partial and include it from every layout, so the URL construction (and the v= cache-buster) lives in exactly one place.

Preview loop. While designing a template, keep the image URL open in a browser tab alongside the Antlers file and hard-refresh. Design at the target dimensions from the config, not at whatever size your browser renders — text that fits at 1200×630 often clips when the real renderer kicks in.

Gotchas and Tips

• Augmentation cost. Now that entries are augmented in the template, deep relationship chains are resolved during image generation. Eager-load the relations you actually use, and avoid looping large collections inside the image template — it runs in a rendering context that is much less forgiving than a normal page request.
• Renderer dependencies. Image generation relies on a headless browser (Browsershot/Puppeteer or similar, depending on your config). Expect missing Chromium, missing fonts, or container sandbox flags to be the top cause of blank/500 responses. Test in the same container you deploy to.
• Fonts and assets. System fonts available in your local environment are often absent in production/Docker. Embed or ship the fonts in your public assets, and use absolute asset URLs in the image template.
• Caching is the #1 source of "it didn't update" bugs. Check the config for cache path/TTL, confirm the generated file actually changed on disk, and make sure your meta tag includes a version query string. CDN and social platform caches (Facebook, X, LinkedIn) are a second layer — use each platform's debugger to force a re-scrape.
• og:image must be an absolute URL. Relative paths silently fail on most scrapers. Use {{ social_media_image url }} or {{ url }} rather than a raw path.
• Errors surface as broken cards, not stack traces. If the image URL returns HTML or a 500, social platforms just show no image. Log and monitor the generation route, and add a smoke test that asserts a 200 with an image content type for a known entry.
• CP Recreate action is per-entry, not bulk-by-default. For site-wide template changes, plan a CLI/queued batch regeneration; do not ask editors to click through hundreds of entries.
• Statamic 6 support is a constraint relaxation, not a behaviour change. The 1.4.0 release simply allows Statamic 6 installs. If you are upgrading, verify the Antlers syntax and any custom tags in your image templates against Statamic 6's Antler changes before assuming the images still render identically.
• Extension points. The config file is the intended surface for template path, dimensions, and route prefix. Prefer overriding config and templates over patching vendor code — the addon's renderer internals are the most likely thing to shift between minor releases.