RSS
RSS in KatanaKit is not a singleton core service. There is no RssService
class and no getInstance() call: the surface is split into three independent
pieces that share one set of types.
- Astro endpoints —
useAstroGenerateRss(),useAstroRssLinkTag(),useAstroCreateRssEndpoint()anduseAstroCreateRssEndpointFromConfig()build the RSS 2.0 XML, the<head>advertising tag and theGEThandler forsrc/pages/rss.xml.ts. They live on thekatanakit-js/adapters/astrosubpath. - Head autodiscovery —
useRssHeadLink()(package root) emits the<link rel="alternate" type="application/rss+xml">tag from aSiteConfig, in any framework. It is the framework-agnostic counterpart ofuseAstroRssLinkTag(). - YouTube feeds —
useBuildYoutubeRssUrl()anduseParseYoutubeRss()build the keyless YouTube channel feed URL and parse its Atom entries into normalized videos, with no API key and zero quota cost.
All three share the RssConfig, RssItem and RssResult types described in the
type reference. Pick the entry point by what you need to
produce:
| You need to… | Use |
|---|---|
| Serve a full feed from an Astro route | useAstroCreateRssEndpointFromConfig() |
| Generate an RSS 2.0 XML string anywhere | useAstroGenerateRss() |
Advertise an existing feed in <head> |
useRssHeadLink() |
| Display a channel’s latest YouTube videos | useBuildYoutubeRssUrl() + useParseYoutubeRss() |
Quick example
Section titled “Quick example”An Astro feed endpoint that reads its metadata from siteConfig (no duplicated
title/description) and maps a content collection:
import { useAstroCreateRssEndpointFromConfig } from "katanakit-js/adapters/astro";import { siteConfig } from "katanakit-js";import { getCollection } from "astro:content";
export const GET = useAstroCreateRssEndpointFromConfig(siteConfig, async () => { const posts = await getCollection("blog");
return posts .sort( (a, b) => new Date(b.data.date).getTime() - new Date(a.data.date).getTime(), ) .slice(0, siteConfig.rss.limit) .map((post) => ({ title: post.data.title, pubDate: post.data.date, link: `/blog/${post.slug}/`, description: post.data.description, }));});The endpoint is only half of the integration: readers and crawlers find
/rss.xml through the autodiscovery tag. useRssHeadLink(siteConfig) produces
it from the same config, so the route and the tag never drift apart.
Type reference
Section titled “Type reference”RssConfig
Section titled “RssConfig”RssConfig is inferred from RssConfigSchema and is the shared input for
useAstroGenerateRss() and the endpoint helpers.
| Field | Type | Default | Notes |
|---|---|---|---|
title |
string |
— | Required. Feed title, escaped into <title>. |
description |
string |
— | Required by the type; may be empty. Channel description. |
site |
string |
— | Required. Base URL; a single trailing slash is trimmed. |
items |
RssItem[] |
— | May be empty — a channel without items is still valid RSS 2.0. |
xmlPath |
string? |
"/rss.xml" |
Path used in the <atom:link rel="self"> element. Not an output file path. |
language |
string? |
"en" |
Written into <language>. |
customData |
string? |
— | Raw XML injected inside <channel>; ]]> sequences are neutralized first. |
xslUrl |
string? |
— | When present, adds an <?xml-stylesheet …?> processing instruction. |
lastBuildDate |
boolean? |
true |
Adds <lastBuildDate> with the current UTC time. Disable for reproducible builds. |
trailingSlash |
boolean? |
— | Declared in the schema but not read by the Astro builder — links are emitted as-is. |
RssItem
Section titled “RssItem”One entry per <item> element. Optional fields are simply omitted from the
output when absent.
| Field | Type | Notes |
|---|---|---|
title |
string |
Required. Escaped with the XML entity set (&, <, >, ", '). |
pubDate |
Date | string |
Required. Formatted as RFC-822 via toUTCString(). Strings go through new Date() first. |
link |
string |
Required. Starting with http → used as-is; anything else gets site prefixed. |
description |
string? |
Optional excerpt. Escaped. |
content |
string? |
Optional full HTML. Wrapped in CDATA; any ]]> is split so it cannot break out of the section. |
categories |
string[]? |
Optional. One escaped <category> element per entry. |
author |
string? |
Optional. Escaped. |
customData |
string? |
Optional raw XML per item (for example an <enclosure>), with ]]> sanitized before insertion. |
Two link gotchas are worth knowing before you map a collection:
- The absolute check is only
link.startsWith("http")— a protocol-relative URL (//cdn.example.com/…) or amailto:would be treated as relative and prefixed withsite. pubDatestrings are not validated. An unparseable string produces<pubDate>Invalid Date</pubDate>instead of failing the build, so validate dates upstream.
import type { RssConfig } from "katanakit-js";
const config = { title: "My Blog", description: "Posts about TypeScript", site: "https://example.com", items: [ { title: "Hello", pubDate: new Date(), link: "/blog/hello/", categories: ["typescript"], }, ],} satisfies RssConfig;RssResult
Section titled “RssResult”RssResult is a Safe Result — a discriminated union that never throws and
narrows cleanly on the ok flag:
type RssResult = | { data: string; error: null; ok: true } | { data: null; error: { message: string; details?: unknown }; ok: false };import { useAstroGenerateRss } from "katanakit-js/adapters/astro";import type { RssResult } from "katanakit-js";
const result: RssResult = useAstroGenerateRss(config);
if (result.ok) { result.data; // full RSS 2.0 XML string} else { result.error.message; // "RSS config requires 'title' and 'site'."}Failure modes:
{ message: "RSS config requires 'title' and 'site'." }when either required field is falsy.{ message: "Failed to generate RSS feed.", details: … }for anything thrown while assembling the XML.
Astro endpoint pipeline
Section titled “Astro endpoint pipeline”The Astro layer covers the feed end to end. Import the four helpers from the adapter subpath:
import { useAstroGenerateRss, useAstroRssLinkTag, useAstroCreateRssEndpoint, useAstroCreateRssEndpointFromConfig,} from "katanakit-js/adapters/astro";| Helper | Layer | Returns |
|---|---|---|
useAstroGenerateRss() |
RSS 2.0 XML builder | RssResult (XML string or error) |
useAstroRssLinkTag() |
<head> advertising |
<link … /> string |
useAstroCreateRssEndpoint() |
Astro GET handler |
(context) => Promise<Response> |
useAstroCreateRssEndpointFromConfig() |
Astro GET handler |
(context) => Promise<Response> from a SiteConfig |
The sections below summarize each layer; the full parameter tables, defaults, failure modes and response headers live on the Astro adapter page and are not duplicated here.
useAstroGenerateRss(config)
Section titled “useAstroGenerateRss(config)”The pure core: takes an RssConfig and returns the complete RSS 2.0 document as
a Safe Result. Call it directly when you manage the Response yourself — a
Cloudflare Worker, a prerender script or a test. The builder escapes every text
node, wraps content in CDATA (splitting ]]> sequences), sanitizes
channel-level and item-level customData against ]]> injection, and emits
guid as the resolved absolute link with isPermaLink="true". The site
trailing slash is trimmed, so relative links resolve predictably.
Full contract: useAstroGenerateRss(config).
useAstroRssLinkTag(config)
Section titled “useAstroRssLinkTag(config)”Returns the standalone <link rel="alternate" type="application/rss+xml"> tag
from { title, xmlPath }, defaulting xmlPath to "/rss.xml". It is the
Astro-only equivalent of useRssHeadLink(): same output shape, but it takes the
two fields directly instead of a SiteConfig. Render it in Astro with
set:html so the tag itself is not escaped.
Full contract: useAstroRssLinkTag(config).
useAstroCreateRssEndpoint(config)
Section titled “useAstroCreateRssEndpoint(config)”Creates the GET handler for src/pages/rss.xml.ts. items accepts a static
array or a sync/async factory, which is the hook for fetching collections and
remote CMS data. The site URL resolves from config.site first, then the Astro
request context (context.site); without either, the handler responds 500
with { "error": "RSS feed requires a 'site' URL." }. On success it returns the
XML with Content-Type: application/xml; charset=utf-8 and a fixed one-hour
Cache-Control — build the Response yourself around useAstroGenerateRss()
if you need another policy.
Full contract: useAstroCreateRssEndpoint(config).
useAstroCreateRssEndpointFromConfig(siteConfig, items)
Section titled “useAstroCreateRssEndpointFromConfig(siteConfig, items)”The zero-duplication variant used in the quick example: it
maps siteConfig.rss.title, siteConfig.rss.description, siteConfig.site,
siteConfig.rss.path and siteConfig.lang onto the config above. Two
siteConfig.rss fields are not enforced: enabled (gate the route
yourself) and limit (slice items in the factory). Use
useAstroCreateRssEndpoint() when the feed needs customData or xslUrl
overrides that do not belong in SiteConfig.
Full contract: useAstroCreateRssEndpointFromConfig(siteConfig, items).
Head autodiscovery
Section titled “Head autodiscovery”useRssHeadLink(config)
Section titled “useRssHeadLink(config)”Returns the serialized RSS autodiscovery tag for a SiteConfig, or an empty
string when the feed is disabled — so it is safe to inject unconditionally.
| Input | Type | Default | Notes |
|---|---|---|---|
config |
SiteConfig |
— | Fail-fast: a null config or a missing rss block throws. |
config.rss.enabled |
boolean |
— | false → returns "". |
config.rss.path |
string |
"/rss.xml" |
Written verbatim into href; not resolved against site. |
config.rss.title |
string? |
config.title |
Attribute value, escaped (&, ", <, >). |
config.rss.description |
string? |
— | Not used to build the tag. |
config.rss.limit |
number |
— | Not used to build the tag. |
import { siteConfig, useRssHeadLink } from "katanakit-js";
useRssHeadLink(siteConfig);// <link rel="alternate" type="application/rss+xml" title="My Site" href="/rss.xml" />Returns the tag as a plain string. Note that href is emitted exactly as
configured, so path: "/feed.xml" points at the current origin; use an absolute
URL if the feed lives on another host. The link title is double-quoted and
attribute-escaped, but single quotes are not, which is fine for the
double-quoted attribute the serializer always emits.
Edge cases:
- A missing
rssblock throws[Seo] SiteConfig.rss is required (useRssHeadLink). Pass rss: { enabled, path, limit }.instead of silently producing a feedless page. - A
null/undefinedconfig throws[Seo] SiteConfig is required …. - Disabled feeds return
""(nevernull), sohead.includes(rssLink)checks and template injection stay simple. useSeoMeta()already appends this exact tag whenrss.enabledistrue, anduseHeadTags()includes it. Only calluseRssHeadLink()directly when you are assembling the head yourself, to avoid duplicate<link>tags.useGenerateMetaTags()deliberately strips the RSS link.
Real use case — a custom server-rendered <head>: useHeadTags() combines
the per-page metas and the autodiscovery link in one call, so an Express or
router-based SSR app advertises the feed without template duplication:
import express from "express";import { siteConfig, useHeadTags } from "katanakit-js";
const app = express();
app.get("/", (_req, res) => { const head = useHeadTags(siteConfig, { title: "Home", description: "Latest posts", });
res .type("html") .send(`<!doctype html><html><head>${head}</head><body>…</body></html>`);});YouTube feeds
Section titled “YouTube feeds”YouTube publishes a public Atom feed per channel at
https://www.youtube.com/feeds/videos.xml, with roughly the latest 15 videos
and basic metadata. Two helpers cover it: one builds the URL, one parses the
response. Neither needs an API key, and neither touches the YouTube Data API
quota.
useBuildYoutubeRssUrl(channelId)
Section titled “useBuildYoutubeRssUrl(channelId)”Builds the keyless channel feed URL with URLSearchParams, so the id is
encoded safely.
import { useBuildYoutubeRssUrl } from "katanakit-js";
useBuildYoutubeRssUrl("UC_x5XG1OV2P6uZZ5FSM9Ttw");// https://www.youtube.com/feeds/videos.xml?channel_id=UC_x5XG1OV2P6uZZ5FSM9TtwTakes the channel id (UC…), not a handle or a vanity URL — the feed endpoint
does not resolve handles. There is no runtime validation: an empty string still
produces a syntactically valid URL (?channel_id=), and the request will simply
come back without entries.
Real use case — a build-time “latest videos” strip: fetch the URL once at
build time, parse it with useParseYoutubeRss(), and ship static markup. If you
prefer a Safe Result over two manual steps, useGetChannelVideosRss() wraps the
fetch plus parse (register it with useInitYoutube() first; an empty apiKey
is fine for the keyless feed):
import { useGetChannelVideosRss, useInitYoutube } from "katanakit-js";
useInitYoutube({ apiKey: "", channelId: "UC_x5XG1OV2P6uZZ5FSM9Ttw" });
const result = await useGetChannelVideosRss();if (result.ok) renderLatest(result.data);useParseYoutubeRss(xml)
Section titled “useParseYoutubeRss(xml)”Parses the channel feed into YoutubeVideoNormalized[]. It is pure and
SSR-safe: a regex pass over <entry> blocks, no DOMParser, no network.
import { useBuildYoutubeRssUrl, useParseYoutubeRss } from "katanakit-js";
const response = await fetch(useBuildYoutubeRssUrl("UC_x5XG1OV2P6uZZ5FSM9Ttw"));const videos = useParseYoutubeRss(await response.text());
videos.slice(0, 6).forEach((video) => { console.log(video.title, video.thumbnail);});Each returned video carries:
| Field | Type | Source |
|---|---|---|
id |
string |
<yt:videoId> |
title |
string |
<title>, entities decoded |
description |
string |
<media:description> |
publishedAt |
string |
<published> |
channelTitle |
string? |
<author><name> |
thumbnails |
{ default, medium, high } |
Derived from the video id (i.ytimg.com) |
thumbnail |
string |
thumbnails.high shortcut |
url |
string |
https://www.youtube.com/watch?v=… |
embedUrl |
string |
Privacy-enhanced youtube-nocookie embed |
durationSeconds |
number? |
Not provided by the feed — enrich separately |
viewCount |
number? |
Not provided by the feed — enrich separately |
Returns the videos newest-first, exactly as the feed serves them. The entity
decoding is a single pass with & handled last, so a double-encoded
&lt; stays as < rather than collapsing into <.
Edge cases:
- Invalid or non-feed XML returns
[]— the parser never throws. - Entries without a
<yt:videoId>are skipped. - Missing optional tags (
<title>,<media:description>,<published>,<author>) fall back to empty strings;channelTitlestaysundefined. - The parser expects the exact tag names YouTube emits and does no XML validation. If the feed format changes, you get fewer (or zero) results instead of an error.
- The feed has no
durationSecondsorviewCount. When you have an API key, pass the ids touseGetVideoDetails()(up to 50) to enrich them.
Real use case — an SSR “shorts/latest videos” section: parse the feed on the
server, enrich ids with useGetVideoDetails(), and render posters from
thumbnail linking to url. Because the feed URL is keyless, local development
and preview builds work without any YouTube credentials.
Related
Section titled “Related”- Astro Adapter — full parameter tables, failure modes and response headers for the four RSS helpers.
- SEO —
SiteConfig,useSeoMeta()and the head pipeline that embeds the autodiscovery link. - API Reference — every export on this page, generated from source.