I needed a calendar people could subscribe to for Sri Lankan public holidays, Poya days and mercantile holidays. I could have pulled in an iCalendar library, but the data is a flat list of dates, so I wrote the generator myself: one function, about 20 lines. This post goes through the parts of RFC 5545 that matter for that case, with output from the real code.
The feeds are part of the holiday widgets and calendar feeds on my site, but nothing below depends on it.
What a one-event feed looks like
I ran the function for the first Poya day in my list, with a fixed timestamp so the output is repeatable:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hirantha.me//Sri Lanka holidays//EN
CALSCALE:GREGORIAN
X-WR-CALNAME:Sri Lanka Poya days
METHOD:PUBLISH
X-PUBLISHED-TTL:PT24H
REFRESH-INTERVAL;VALUE=DURATION:P1D
X-WR-TIMEZONE:Asia/Colombo
BEGIN:VEVENT
UID:20260103-duruthu-full-moon-poya-day@hirantha.me
DTSTAMP:20261013T080000Z
DTSTART;VALUE=DATE:20260103
DTEND;VALUE=DATE:20260104
SUMMARY:Duruthu Full Moon Poya Day
URL:https://hirantha.me/tools/sri-lanka-holidays
DESCRIPTION:Public and bank holiday in Sri Lanka. Full list: https://hirantha.me/tools/sri-lanka-holidays
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR
Each piece is there for a reason.
All-day events and the exclusive DTEND
A holiday has a date, not a time. In iCalendar that is DTSTART;VALUE=DATE:20260103, with no time and no time zone. The trap is DTEND. For a DATE value it is exclusive: an event on 3 January ends on 4 January. If you write the same day for both, many apps treat it as a zero-length event or drop it.
So the code adds one day to the start. It does the arithmetic on UTC milliseconds instead of cutting the string, so month and year ends work:
const DAY = 86_400_000;
const utc = (iso: string) => {
const [y, m, d] = iso.split("-").map(Number);
return Date.UTC(y, m - 1, d);
};
const iso = (ms: number) => new Date(ms).toISOString().slice(0, 10);
const start = x.date.replace(/-/g, "");
const next = iso(utc(x.date) + DAY).replace(/-/g, "");
I ran a holiday on 2026-12-31 through it and got DTSTART;VALUE=DATE:20261231 and DTEND;VALUE=DATE:20270101. Using UTC avoids daylight saving shifts. Sri Lanka has none now, but the code runs on servers in other zones.
A UID that survives regeneration
A subscribed feed is fetched again and again, and the client matches events by UID. If the UID changes every time, each refresh adds duplicates. If it is stable, the client updates in place.
I build it from the data itself, so nothing needs storing:
`UID:${start}-${x.name.toLowerCase().replace(/[^a-z0-9]+/g, "-")}@hirantha.me`
That gives 20260103-duruthu-full-moon-poya-day@hirantha.me. The domain at the end follows the RFC's advice to make UIDs globally unique. There is a unit test that collects every UID from a 25-event file and checks the set has the same size as the list.
The limit: the UID includes the name. If the source renames a holiday, clients will see one event removed and one added rather than an edit. For a gazetted list that rarely changes, I accepted that.
DTSTAMP changes, UID does not
DTSTAMP is when the feed was generated, so it is new Date() on each request. The function takes the stamp as a parameter (stamp: Date = new Date()), which is what let me pin it in the test and in the output above. Passing the clock in is the one testing habit I would copy into any generator like this.
TRANSP so holidays don't block your time
TRANSP:TRANSPARENT means the event does not make you busy. Without it, an all-day event shows you as busy for the whole day to anyone looking at your free/busy. A public holiday is information, not a meeting, so every event gets it.
Telling clients how often to refresh
Clients decide for themselves how often to poll, and the standards are loose. I send three hints, only for the subscribed feed:
-
REFRESH-INTERVAL;VALUE=DURATION:P1Dis the RFC 7986 property. -
X-PUBLISHED-TTL:PT24His an older, non-standard hint some clients read. -
X-WR-TIMEZONEandX-WR-CALNAMEare non-standard but widely read, for the default zone and the name shown when you subscribe.
These are hints. Some apps ignore them and refresh when they like, which is why the HTTP caching below matters too. The one-off download option (without feed: true) leaves them out.
Escaping and line endings
Text values need \, ; and , escaped with a backslash. The whole escaper is one line:
const icsText = (s: string) => s.replace(/\\/g, "\\\\").replace(/;/g, "\\;").replace(/,/g, "\\,");
The backslash goes first, otherwise the backslashes you just added would be escaped again. With the name A, B; C the output is SUMMARY:A\, B\; C. Note the URL is not escaped, since it is a URI value, not TEXT.
Lines must end in CRLF, including the last one. I join with "\r\n" and add a trailing one, and a test fails on any \n not preceded by \r: !/[^\r]\n/.test(ics). A bare LF works in some apps and breaks others, so the test is cheap insurance.
One thing I did not do: the RFC says lines longer than 75 octets should be folded onto continuation lines that start with a space. My DESCRIPTION line above is over 100 characters and is not folded. I have not tested every client against it, it is a "should" I am not meeting, and a stricter parser could complain. If you have long text, write a fold() function; I would do it with a byte count, not a character count, once non-ASCII text appears.
The HTTP side
The route is a Next.js handler that picks the filter for the requested file name and returns the text:
return new Response(body, {
headers: {
"Content-Type": "text/calendar; charset=utf-8",
"Content-Disposition": `inline; filename="${file}"`,
"Cache-Control": "public, max-age=21600, s-maxage=21600",
"X-Robots-Tag": "noindex",
},
});
I checked the live response, and those headers come back as written. text/calendar is the registered type, so apps offer to subscribe. Six hours of cache means a refresh every day costs the server at most a few regenerations. noindex keeps the raw .ics files out of search results. An unknown file name returns 404.
Because the feed comes from a static list in code, the three holiday calendars are just filters over the same array: all holidays, those whose name is a Poya day, and those flagged mercantile. The all-holidays list has 51 entries, 25 of them Poya days.
What this cannot tell you
The dates come from the Central Bank of Sri Lanka's published holiday list, stored as a list in the code. The feed is only as current as my last edit: when a new year's list is gazetted I have to add it, and until then the feed simply ends. A feed that refreshes once a day will also lag behind any late change to the list.
Takeaways
- Treat DATE-valued
DTENDas exclusive, and compute it with date arithmetic. - Derive the UID from the data so it is stable without storage.
- Add
TRANSP:TRANSPARENTto informational events. - Escape the backslash first, end every line with CRLF, and test both.
- Know which "should" you are skipping; mine is line folding.
If you have written iCalendar feeds, which clients gave you the most trouble: Google Calendar, Apple Calendar or Outlook, and what did they do differently?
This article was written with the help of AI. The code, numbers and sources come from my own project and were checked against it before publishing.
Top comments (0)