Generating valid .ics calendar feeds at build time

A few weeks ago I shipped a feature I'd been putting off because it felt like it needed a backend: subscribable calendar feeds. "Add this holiday to Google Calendar." "Subscribe to all your country's public holidays so they show up in Apple Calendar forever."

Every calendar competitor has this. My site had none. The catch: the whole thing is a static export — next build produces a folder of HTML/CSS/JS that I drop on Cloudflare Pages. No server, no API routes at request time, no ISR. So how do you serve a .ics feed that a calendar app polls every few hours?

Turns out you don't need a server at all. Here's the approach, the RFC 5545 gotchas that bit me, and the parts I'd tell my past self.

The "aha": a feed is just a file

A .ics subscription feed is not a live API. It's a static text file that calendar clients re-fetch on a schedule. So for a static site, the idiomatic move is a post-build emitter: after next build, run a Node script that walks your data and writes assets straight into out/.

# scripts/deploy.sh
npx next build
node scripts/emit-feeds.mjs   # writes .ics + .json into out/

That's the entire architecture. The emitter reads the same JSON the pages render from, so the feeds can never drift out of sync with the site — there's one source of truth. It emits:

a per-year feed (holidays-de-2026.ics)
a per-holiday feed (one event, for the "download this day" button)
an all-years subscription feed (the one you point webcal:// at)
and, almost for free in the same loop, a JSON API under out/api/

No new pages, no new routes. Just files.

RFC 5545: all-day events are sneakier than they look

I assumed an all-day event on Jan 1 would be DTSTART:20260101, DTEND:20260101. Wrong. DTEND is exclusive. A one-day all-day event ends on Jan 2:

BEGIN:VEVENT
UID:de-2026-neujahr@calendana.com
DTSTAMP:20260614T101500Z
DTSTART;VALUE=DATE:20260101
DTEND;VALUE=DATE:20260102
SUMMARY:Neujahr
TRANSP:TRANSPARENT
CATEGORIES:Holiday
END:VEVENT

Get this wrong and some clients render a zero-length event, or silently drop it. Other things the spec is quietly strict about, all of which I learned by importing broken files into Apple Calendar and watching nothing appear:

CRLF line endings. Not \n. \r\n, everywhere.
75-octet line folding. Lines longer than 75 bytes (not chars — bytes) must be folded, with continuation lines starting with a single space. The byte distinction matters the moment you have non-ASCII content; you must never split a multi-byte UTF-8 codepoint across the fold.
TEXT escaping. Commas, semicolons, backslashes and newlines in SUMMARY/DESCRIPTION have to be escaped (\, \; \\ \n).
A stable UID. If the UID changes between rebuilds, every subscriber gets duplicate events on the next poll. Mine is deterministic: {locale}-{year}-{key}@domain.

The folding function is the bit worth copying, because the byte-vs-char trap is easy to miss:

function foldLine(line) {
  const bytes = new TextEncoder().encode(line);
  if (bytes.length <= 75) return line;
  const dec = new TextDecoder();
  const out = [];
  let start = 0;
  let limit = 75;
  while (start < bytes.length) {
    let end = Math.min(start + limit, bytes.length);
    // back off if the cut lands mid-codepoint (UTF-8 continuation = 10xxxxxx)
    while (end < bytes.length && (bytes[end] & 0xc0) === 0x80) end--;
    out.push((start === 0 ? "" : " ") + dec.decode(bytes.slice(start, end)));
    start = end;
    limit = 74; // continuation lines spend 1 octet on the leading space
  }
  return out.join("\r\n");
}

The zero-infra trick: deeplinks

The .ics files cover "download" and "subscribe." But the highest-intent button — "Add to Google Calendar" — needs no file at all. Google and Outlook both accept a URL that pre-fills a new event:

function googleHref({ name, date }) {
  const compact = (iso) => iso.replace(/-/g, "");
  const next = nextDay(date); // remember: end is exclusive
  const p = new URLSearchParams({
    action: "TEMPLATE",
    text: name,
    dates: `${compact(date)}/${compact(next)}`,
  });
  return `https://calendar.google.com/calendar/render?${p}`;
}

One <a href>. No JS, no library, works on a static page. (Outlook's equivalent is outlook.live.com/calendar/0/deeplink/compose — note the deeplink segment; I shipped it once without it and the prefill silently failed.)

Serving the right MIME type on a static host

If you serve .ics as text/plain, some clients refuse it. On Cloudflare Pages a single _headers file in public/ handles it:

/*.ics
  Content-Type: text/calendar; charset=utf-8
  Cache-Control: public, max-age=86400
/api/*
  Content-Type: application/json; charset=utf-8
  Access-Control-Allow-Origin: *

The part that's actually hard: 15 languages

This is the bit I keep coming back to. The site runs in 15 locales, and the temptation with any multilingual feature is to write the English microcopy once and machine-translate it ×15. Don't. For a content/SEO site that's a fast track to thin, near-duplicate pages that search engines won't index — and for a calendar, it's also just wrong. A Mexican user wants "Agregar a Google Calendar" for "días festivos"; a Spaniard wants "Añadir" for "festivos"; an Argentine says "feriados." Same language, three different words. Those got hand-written per locale, sharing one strings file that both the Node emitter and the React components read, so the button label and the feed's calendar name always agree.

That single-source-of-everything theme — one holiday JSON feeding the pages, the feeds, and the API; one strings file feeding the emitter and the UI — is what kept this feature from becoming a maintenance swamp.

Where it lives

The site is Calendana — printable calendars plus public-holiday and school-holiday data for a bunch of countries, all static, all free, ad-supported, no login. The calendar-export work is live on every holiday page now. If you just want to see the feed format, grab one and open it:

https://calendana.com/de/holidays/2026/holidays-de-2026.ics

or the JSON, if you're building something:

https://calendana.com/api/holidays/de/2026.json

Takeaways

"Needs a backend" is often a reflex, not a requirement. A subscription feed is a file. A "create event" button is a URL. Both fit a static site fine.
Read the RFC. All-day DTEND is exclusive, lines fold on bytes, endings are CRLF. The spec is boring and it is right.
Generate sibling artifacts from one source. Pages, .ics, and JSON all come from the same data in one build step, so they can't disagree.
Localize the words, not just the dates. Especially when "the same language" means different words in different countries.

Happy to answer questions on the emitter or the folding/escaping details in the comments — that's where most of the sharp edges were.

推荐订阅源

DEV Community