Skip to content

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 keyNameUsed byLookCanvas size
bbv2BB Brand V2Bocce's Bakery (v2 brand style)Peach #f6e3d4 background, black digit boxes, white Gelica digits, Brandon Grotesque labels1120 × 375
bbBB BrandBocce's Bakery (v1 brand style)White background, dark #2C2A26 boxes, Gelica / Brandon Grotesque800 × 200
mppMPP BrandMy Perfect PetCream #FFFAF5 background, coral #EE6446 outlined boxes, Mohr SemiBold1080 × 290
defaultDefaultFallback for unknown brand keysBlack background, orange accents800 × 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/
FileRole
api/timer.jsGET /timer: validates params, returns image/gif
api/brands.jsGET /brands: lists brand keys with preview links
api/health.jsGET /health
api/index.jsGET /: preview page and embed-code generator
api/preview.jsSame preview page at /api/preview (relative embed URLs)
lib/brands.jsBrand definitions
lib/gifGenerator.jsDraws frames. Registers the fonts in fonts/ at startup.
lib/dateUtils.jsParses due: Unix seconds / milliseconds, ISO 8601, common date strings
lib/previewPage.jsHTML for the preview page
fonts/Gelica-Bold.otf, Brandon.otf (Brandon Grotesque), Mohr-SemiBold.woff2 (commercial fonts)
server.jsFastify server for local development only
vercel.jsonRoutes /timer, /brands, /health, / to the functions. Bundles fonts/** and lib/** into each function.

Endpoints ​

RouteReturns
GET /timerThe 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/previewSame 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:

ParameterRequiredDefaultNotes
dueYes—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
brandNodefaultbbv2, bb, mpp, default. Unknown keys fall back to default.
tzNoAmerica/New_YorkOnly applies to non-ISO date strings (e.g. 2026-11-27 23:59)
width / heightNoBrand's sizePixels. Overriding can crop the layout.
framesNo30Max 60. Each frame is one second.

Where it's deployed ​

Repositorygithub.com/crupko93/ant-timer, branch master
VercelProject ant-timer. Git-connected: production deploys from master, other branches get previews.
Production URLhttps://ant-timer.vercel.app
Environment variablesNone in production. PORT, HOST for local dev only.
Database / storageNone

How to use (marketing / Klaviyo) ​

  1. Open https://ant-timer.vercel.app/.
  2. Pick the Brand Theme and the Due Date, then press Update Preview.
  3. Copy the Embed Code (an img tag pointing at /timer?brand=…&due=…).
  4. In Klaviyo, add an HTML block (or edit the template's HTML) and paste the tag where the timer should appear.
  5. 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:

html
<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 alt text. 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.

bash
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:00

Add a new brand ​

  1. Add an entry to brands in lib/brands.js. Copy mpp or bbv2 as 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.
  2. If it needs a new font, add the file to fonts/ and register it in the fonts list in registerFonts() in lib/gifGenerator.js. The fontConfig object in brands.js is not what registers fonts. Missing files are skipped with a warning and the canvas falls back to a default font.
  3. Add the brand to the <select> and the brand cards in lib/previewPage.js, so marketing can pick it.
  4. Test locally, push a branch, check the Vercel preview URL, then merge to master.

Testing ​

There is no automated test suite. Check by hand:

bash
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 ​

SymptomCause
Timer is off by a few hoursdue 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 GIFThe 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 404Use / instead (see Endpoints)
Unknown brand shows black/orangeThe brand key isn't in lib/brands.js, so it fell back to default
Email loads slowlyGIFs 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), while package.json and the README declare the code MIT. The repo is private. Keep it that way, and check the font licences before sharing it.

Antelope Themes Documentation

Enter the password to access this site.