Email Countdown Timer
Overview
Email Countdown Timer (repo ant-timer) is a small service that renders animated countdown-timer GIFs for email campaigns. Email clients don't run JavaScript, so the server works out the time left when the email is opened (when the image is requested) and returns a GIF that counts down from there.
- Input: a due date in the image URL (
/timer?brand=bbv2&due=...) - Output: a looping GIF, 30 frames at 1 s each, showing DAYS / HOURS / MINS / SECS in the brand's style, or "OFFER EXPIRED" after the due date
- Responses are sent with
Cache-Control: no-cache, no-store, must-revalidate, so every open renders a fresh countdown
It is not a Shopify app. It has no Shopify app record, no database and no secrets.
Where it's used
Used in Klaviyo email campaigns for the brands that have a theme in the service:
| Brand key | Name | Used by | Look | Canvas size |
|---|---|---|---|---|
bbv2 | BB Brand V2 | Bocce's Bakery (v2 brand style) | Peach #f6e3d4 background, black digit boxes, white Gelica digits, Brandon Grotesque labels | 1120 × 375 |
bb | BB Brand | Bocce's Bakery (v1 brand style) | White background, dark #2C2A26 boxes, Gelica / Brandon Grotesque | 800 × 200 |
mpp | MPP Brand | My Perfect Pet | Cream #FFFAF5 background, coral #EE6446 outlined boxes, Mohr SemiBold | 1080 × 290 |
default | Default | Fallback for unknown brand keys | Black background, orange accents | 800 × 200 |
There are no theme-side hooks. The timer only lives in email HTML.
Architecture
Klaviyo email <img src="https://ant-timer.vercel.app/timer?brand=…&due=…">
│ (request at open time)
▼
Vercel project "ant-timer"
api/timer.js → lib/dateUtils.js (parse due) → lib/gifGenerator.js (@napi-rs/canvas + gif-encoder-2)
└── lib/brands.js (colours, fonts, sizes) + fonts/| File | Role |
|---|---|
api/timer.js | GET /timer: validates params, returns image/gif |
api/brands.js | GET /brands: lists brand keys with preview links |
api/health.js | GET /health |
api/index.js | GET /: preview page and embed-code generator |
api/preview.js | Same preview page at /api/preview (relative embed URLs) |
lib/brands.js | Brand definitions |
lib/gifGenerator.js | Draws frames. Registers the fonts in fonts/ at startup. |
lib/dateUtils.js | Parses due: Unix seconds / milliseconds, ISO 8601, common date strings |
lib/previewPage.js | HTML for the preview page |
fonts/ | Gelica-Bold.otf, Brandon.otf (Brandon Grotesque), Mohr-SemiBold.woff2 (commercial fonts) |
server.js | Fastify server for local development only |
vercel.json | Routes /timer, /brands, /health, / to the functions. Bundles fonts/** and lib/** into each function. |
Endpoints
| Route | Returns |
|---|---|
GET /timer | The countdown GIF (parameters below). 400 JSON if due is missing or unparseable. |
GET /brands | { available: [...], details: [{ key, name, preview }] } |
GET /health | { "status": "ok", "timestamp": ... } |
GET / | Preview page with a brand picker, a date picker and the embed code |
GET /api/preview | Same preview page (embed code without the domain until you press Update Preview) |
There is no /preview route in production (vercel.json doesn't route it, so it returns 404). Use https://ant-timer.vercel.app/.
GET /timer parameters:
| Parameter | Required | Default | Notes |
|---|---|---|---|
due | Yes | — | ISO 8601 with offset (recommended, e.g. 2026-11-27T23:59:00-05:00), Unix seconds (10 digits) or milliseconds (13 digits), or a common date string |
brand | No | default | bbv2, bb, mpp, default. Unknown keys fall back to default. |
tz | No | America/New_York | Only applies to non-ISO date strings (e.g. 2026-11-27 23:59) |
width / height | No | Brand's size | Pixels. Overriding can crop the layout. |
frames | No | 30 | Max 60. Each frame is one second. |
Where it's deployed
| Repository | github.com/crupko93/ant-timer, branch master |
| Vercel | Project ant-timer. Git-connected: production deploys from master, other branches get previews. |
| Production URL | https://ant-timer.vercel.app |
| Environment variables | None in production. PORT, HOST for local dev only. |
| Database / storage | None |
How to use (marketing / Klaviyo)
- Open
https://ant-timer.vercel.app/. - Pick the Brand Theme and the Due Date, then press Update Preview.
- Copy the Embed Code (an
imgtag pointing at/timer?brand=…&due=…). - In Klaviyo, add an HTML block (or edit the template's HTML) and paste the tag where the timer should appear.
- Send a test email and check the timer counts down and the time left is right.
Check the time zone
The preview page reads the date picker in your browser's local time zone and converts it to UTC in the embed URL. If you're not in US Eastern time, either set your computer's time zone or write the URL by hand with an explicit offset, e.g. due=2026-11-27T23:59:00-05:00 (EST) or -04:00 (EDT).
Example tag:
<img src="https://ant-timer.vercel.app/timer?brand=bbv2&due=2026-11-27T23:59:00-05:00"
alt="Countdown Timer" style="max-width: 600px; width: 100%;">Tips:
- Always set
alttext. Some clients block images by default. - The GIF loops every 30 seconds (30 one-second frames). That's normal for email timers. Each new open renders a fresh countdown.
- After the due date the GIF shows OFFER EXPIRED.
- Some email clients proxy or cache images, so a re-opened email can show the time from an earlier open.
How to update & deploy
Deploys are automatic: merge to master and Vercel builds production. Other branches get preview deployments you can test before merging.
git clone git@github.com:crupko93/ant-timer.git && cd ant-timer
npm install
npm run dev # node --watch server.js → http://localhost:3000
# open http://localhost:3000/ (preview) or /timer?brand=mpp&due=2026-12-31T23:59:00-05:00Add a new brand
- Add an entry to
brandsinlib/brands.js. Copympporbbv2as a starting point. Keys: colours (backgroundColor,textColor,labelColor,digitBackgroundColor,digitBorderColor,separatorColor), fonts (font,labelFont,separatorFont,digitFontFamily,labelFontFamily), layout (boxWidth,boxHeight,boxSpacing,borderWidth,cornerRadius,labelOffset,separatorDotRadius,separatorDotSpacing,labelLetterSpacing),expiredMessage,width,height. - If it needs a new font, add the file to
fonts/and register it in thefontslist inregisterFonts()inlib/gifGenerator.js. ThefontConfigobject inbrands.jsis not what registers fonts. Missing files are skipped with a warning and the canvas falls back to a default font. - Add the brand to the
<select>and the brand cards inlib/previewPage.js, so marketing can pick it. - Test locally, push a branch, check the Vercel preview URL, then merge to
master.
Testing
There is no automated test suite. Check by hand:
curl -s https://ant-timer.vercel.app/health
curl -s https://ant-timer.vercel.app/brands
curl -s -o /tmp/t.gif -w "%{http_code} %{content_type}\n" \
"https://ant-timer.vercel.app/timer?brand=bbv2&due=2026-12-31T23:59:00-05:00"Then open the GIF and confirm the fonts rendered (not a fallback font) and the numbers are right.
Troubleshooting & known limits
| Symptom | Cause |
|---|---|
| Timer is off by a few hours | due had no offset and was read in a different zone. ISO strings without an offset are parsed in the server's zone (UTC on Vercel). tz only applies to non-ISO strings. Always include the offset. |
| Wrong font in the GIF | The font file is missing from fonts/, or isn't registered in lib/gifGenerator.js. Check the function logs for Font file not found. |
/preview returns 404 | Use / instead (see Endpoints) |
| Unknown brand shows black/orange | The brand key isn't in lib/brands.js, so it fell back to default |
| Email loads slowly | GIFs are large (the bbv2 GIF is about 460 KB at 1120 × 375). Lower frames (e.g. frames=15) for a smaller file. |
fonts/holds commercial fonts (Gelica, Brandon Grotesque, Mohr), whilepackage.jsonand the README declare the code MIT. The repo is private. Keep it that way, and check the font licences before sharing it.