Build-Time ICS Calendar Feeds for Static Sites

A founder details a technical playbook for generating subscribable .ics calendar feeds without a backend. This method leverages post-build scripts to ensure static site compatibility and RFC 5545 compliance.

The founder 'mark_b5f4ffdd8e7cd58' reports solving a common static site limitation: serving subscribable .ics calendar feeds. Instead of a backend, the approach uses a post-build Node script to generate static .ics files, which are then deployed alongside other assets. This method ensures calendar clients can re-fetch event data on a schedule without server-side computation.

Static Files, Not Live APIs

The core insight is that an .ics subscription feed functions as a static text file, not a live API endpoint. Calendar clients poll this file on a schedule. For a static site, this enables a post-build emitter approach: after next build, a Node script runs to process data and write .ics assets directly into the out/ directory. The founder provides a shell script snippet:

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

This architecture reads from the same JSON data used to render site pages, preventing data drift between the site and the calendar feeds. The emitter generates multiple feed types: a per-year feed (e.g., holidays-de-2026.ics), a per-holiday feed for single event downloads, an all-years subscription feed, and a JSON API under out/api/ as a byproduct. No new pages or routes are required; only static files are produced.

RFC 5545 Specifics: Common Pitfalls

Implementing .ics feeds requires strict adherence to RFC 5545, the iCalendar specification. The founder reports encountering several non-obvious requirements that caused issues with calendar clients, particularly Apple Calendar:

1. DTEND Exclusivity. For all-day events, DTEND is exclusive. A one-day event on January 1st must specify DTEND:20260102, not DTEND:20260101. Failure to observe this, the founder claims, can result in clients rendering zero-length events or silently dropping them. The provided VEVENT example demonstrates the correct DTEND for an all-day event:

   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
   

2. CRLF Line Endings. The specification mandates \r\n (carriage return, line feed) for all line endings, not just \n.

3. 75-Octet Line Folding. Lines exceeding 75 bytes (not characters) must be folded. Continuation lines begin with a single space. This byte-level distinction is critical for multi-byte UTF-8 characters, which must not be split across folds.

4. TEXT Escaping. Specific characters—commas (,), semicolons (;), backslashes (\), and newlines (\n)—within SUMMARY or DESCRIPTION fields must be escaped (e.g., \,, \;, \\, \n).

5. Stable UIDs. The UID field must remain consistent across rebuilds. If a UID changes, subscribers will receive duplicate events on subsequent polls. The founder's deterministic UID format is {locale}-{year}-{key}@domain.

What We'd Change

The build-time generation of .ics feeds is a sound strategy for static sites, effectively offloading server-side computation. However, the approach, as detailed, presents specific considerations for scalability and maintainability.

For sites with a rapidly growing number of events or frequent updates, relying solely on full site rebuilds for calendar feed changes may introduce latency. A more dynamic solution might involve triggering the emit-feeds.mjs script via a webhook after data changes, rather than only during a full next build. This would allow for faster updates to calendar feeds without redeploying the entire site. Furthermore, while a custom Node script offers control, dedicated iCalendar libraries (e.g., ical-generator for Node.js) could abstract away some RFC 5545 complexities, reducing the risk of subtle parsing errors and improving code maintainability. Such libraries often handle line folding, escaping, and DTEND calculations automatically.

Finally, the founder's experience with specific client behaviors, such as Apple Calendar silently dropping events, highlights the need for robust validation. Integrating automated .ics validation tools into the build pipeline could proactively catch RFC compliance issues before deployment, rather than relying on manual testing with various calendar applications. This would shift error detection left in the development cycle.

This build-time approach for .ics feeds demonstrates how static site architectures can extend to traditionally server-side features. By understanding and adhering to the underlying protocol specifications, developers can deliver rich functionality while maintaining the performance and cost benefits of static deployments. The key lies in meticulous implementation and a proactive approach to validation against client expectations.

The investor read

The signal highlights a broader trend: the continuous push to offload server-side logic to build-time or client-side operations, particularly within the static site ecosystem. This reduces hosting costs and operational complexity, making niche features like subscribable calendar feeds accessible to bootstrapped or micro-SaaS projects. Investable opportunities may exist in specialized build tools or platform features that abstract away RFC complexities for static site generators, enabling developers to integrate such functionality with less custom code. For products like the founder's, this tactic is a deliberate lifestyle play, optimizing for low operational overhead rather than scaling infrastructure.