Guide · Vercel

Use coolreadme cards on a Vercel-deployed profile site

If you ship a personal site on Vercel, you can embed coolreadme cards alongside (or instead of) your GitHub profile README. Same endpoint, same animation, no extra config.

Same endpoint, different surface

Every /api/* endpoint on coolreadme.xyz returns an image with `Cache-Control: public, max-age=7200, s-maxage=7200` and `Access-Control-Allow-Origin: *`. That means you can drop an `<img src="https://coolreadme.xyz/api/cinematic?user=yourname">` into any HTML page on any domain — Vercel-deployed Next.js, Astro, plain static site, doesn't matter.

Next.js Image vs plain img

If your Vercel site is Next.js, use a plain `<img>` tag so the browser loads the SVG directly from coolreadme.xyz. `next/image` can proxy and rasterize the response, which removes SVG animation and adds unnecessary image-optimization work.

Edge runtime affinity

coolreadme.xyz is itself deployed on Vercel's edge runtime. When your Vercel site fetches a coolreadme card from the same region, you get minimal latency — typically sub-50ms. Combined with the 2-hour edge cache, repeat visitors load instantly.

Open Graph for your profile site

Most social networks require PNG or JPEG for reliable Open Graph previews. Export a coolreadme SVG to PNG during your build, then reference that static PNG from your metadata instead of pointing crawlers at the live SVG endpoint.

Build-time vs request-time

Don't try to fetch coolreadme card binaries at build time and serve them statically. They're meant to be live — the cat streak card, for example, reflects the *current* GitHub contribution graph. Embed the URL, not the data.

Step by step

  1. 01

    Deploy your site to Vercel

    Any framework. coolreadme cards work in plain HTML.

  2. 02

    Embed cards as <img>

    Use plain <img src="..."> not next/image for animated SVG cards.

  3. 03

    Wire OG images

    Export a card to PNG at build time before using it as an Open Graph image.

  4. 04

    Ship

    Vercel deploys in seconds. Cards are edge-cached on coolreadme.xyz for 2h.