Overview

@seedprotocol/feed turns the published items of a model into RSS 2.0, Atom and JSON Feed documents, with paging, monthly archives and ready-made HTTP handlers. @seedprotocol/feed-hyper writes the same documents into a Hyperdrive and distributes them peer to peer. Both read items through @seedprotocol/query, so they see every app's published items of a schema, from EAS, with revoked items left out.

import { handleFeedRequest, setSiteConfig } from '@seedprotocol/feed'
import { publishFeed, serveFeed } from '@seedprotocol/feed-hyper'

For a walkthrough, see Serve published items as a feed. This page covers installation, configuration and caching. The API is on createFeed and handlers and Hyper distribution.

Install

npm install @seedprotocol/feed
# Only if you distribute feeds over Hyperswarm:
npm install @seedprotocol/feed-hyper

Both packages have a single entry point (.) and no subpaths. They ship ESM; the require condition points at the same ESM file.

What's in the feed package

To render these fields in a React app, use useNormalizedFeedItemFields and the SeedMedia* components from @seedprotocol/react.

initializeFeedPlatform

Makes item reads work: it keeps the EAS and Arweave clients already registered (by a host app or a running SeedClient) and registers the Node ones for whichever is missing. It's query's initializeQueryPlatform under the feed's name. You don't have to call it: handleFeedRequest, handleArchiveFeedRequest and getFeedItemsBySchemaName call it themselves. Call it at startup only to choose the Arweave gateway.

function initializeFeedPlatform(options?: { arweaveDomain?: string }): Promise<void>
function teardownFeedPlatform(): Promise<void>

The first call wins: later calls return immediately and ignore their options. arweaveDomain, when you pass it, becomes the Arweave host even when a client was already registered, and locks it, so gateway probing won't move reads off it; a host from the environment or the default isn't locked. teardownFeedPlatform() only lets the next call run again; registered clients stay.

Every Arweave link in a feed item, in a link field or inside Html, is written on this public host, because feed readers are outside your app: a local Hyper sidecar address is never used, and a client whose gateway endpoints are resolved uses its arweaveDomain. Links to an item's own storage transaction take the /raw/ form (https://arweave.net/raw/<txId>). A guid keeps the value it was given and isn't moved onto the public host; a stored item's default guid is ar://<txId> (field mapping).

If rich-text bodies come out as gateway URLs instead of HTML, no read gateway returned them (see query's SeedRecord).

setSiteConfig

Sets the channel metadata of every feed this process generates: title, home page, feed URL, author and so on.

function setSiteConfig(overrides: SiteConfigOverrides): FeedConfig

It returns the resolved config. The config is process-wide and synchronous, so call it once at startup.

FeedConfig fields

<year> in the default copyright is the year the module was loaded.

How overrides merge

• Each call merges onto Seed Protocol's defaults, not onto your previous call. setSiteConfig({ title: 'A' }) followed by setSiteConfig({ siteUrl: 'https://b.example' }) leaves the title at Seed Protocol.
• author is merged field by field.

Example

import { setSiteConfig } from '@seedprotocol/feed'

setSiteConfig({
  title: 'My Blog',
  description: 'Posts from my Seed app',
  siteUrl: 'https://blog.example.com',
  feedUrl: 'https://feeds.example.com',
  author: { name: 'My Blog', email: 'editor@example.com', link: 'https://blog.example.com' },
})

getSiteConfig, resetSiteConfig and resolveSiteConfig

function getSiteConfig(): FeedConfig
function resetSiteConfig(): void
function resolveSiteConfig(overrides?: SiteConfigOverrides, base?: FeedConfig): FeedConfig
const DEFAULT_SITE_CONFIG: FeedConfig

• getSiteConfig() returns a copy of the current process config.
• resetSiteConfig() restores the defaults.
• resolveSiteConfig(overrides, base) merges overrides onto base (default: the current process config, not the defaults) with the same field-by-field author merge, without changing anything. This is what the handlers and createFeed do with their siteConfigOverrides argument.
• DEFAULT_SITE_CONFIG is the default object. Don't mutate it.

SiteConfigOverrides is Partial<FeedConfig> with author also partial.

Environment variables

The variables the feed package reads. Values are read when used, mostly per request, except where noted.

Feed output

So with FEED_ITEM_URL_BASE=https://blog.example.com and FEED_ITEM_URL_PATH=posts, item links become https://blog.example.com/posts/<seedUid>. siteUrl in the site config never affects item links. The full link rules are under Field mapping.

Caching

The TTLs (IMAGE_METADATA_TTL too) and CACHE_DIR are read once, when the first request creates the feed's cache manager; call resetCacheManager() to make the next request read them again. Query reads the same variables, and CACHE_MAX_AGE, once per process for its own cache.

Image metadata

Both handlers probe Arweave for the image an item's enclosure uses, to find its type, size and dimensions. For image items that's the item's own storage transaction; for other schemas it's the feature or cover image (Field mapping lists the fields) when its URL is an Arweave gateway URL and the item doesn't already give its size and type. Up to 8 probes run at once. Gateways are tried in order until one answers; only an error or a non-ok status moves on to the next. A result is cached while IMAGE_METADATA_ENABLED is on, even with CACHE_ENABLED=false, including "not an image". When no gateway answers, nothing is cached and the next build probes again; the item keeps the image link it has, typed image/jpeg in RSS. createFeed doesn't probe.

Inherited from query, eas and arweave

Item reads also follow the chain, indexer and Arweave gateway variables (EAS_CHAIN_ID, EAS_ENDPOINT, ARWEAVE_HOST, ARWEAVE_READ_GATEWAYS and their aliases) and NODE_ENV, listed on @seedprotocol/query. Two of them do more here: EAS_CHAIN_ID also picks the explorer that item links default to, and ARWEAVE_READ_GATEWAYS also goes into the default image probe list.

@seedprotocol/feed-hyper reads no environment variables of its own. seed-feed publish and publishFeed generate through the feed package, so everything above applies to them.

loadFeedConfig

Returns the feed settings the environment variables above resolve to. Useful for logging your configuration at startup.

function loadFeedConfig(): {
  itemUrlBase: string
  itemUrlPath: string
  pageSize: number
  richTextDataUriImages: 'omit_items' | 'include_items'
}

Caching

There are two caches, both on by default and both under CACHE_DIR:

1. Feed documents (this package). handleFeedRequest and handleArchiveFeedRequest store each generated document in memory and as a JSON file (post-rss.json, post-rss-page-2.json, post-atom-archive-2026-9.json and so on), keyed by schema, format and page or archive month. The first page is checked on every request: the handler asks query for the page's items and rebuilds the document only when query's collection changed. Later pages and archives are served as stored until their TTL runs out. createFeed doesn't cache.
2. Assembled items (@seedprotocol/query), under collections/ and items/. When the feed reads items, query asks EAS what changed and only re-assembles changed items. See query caching.

What that means for a request to /posts/rss:

• Hit: the stored document, with X-Cache: HIT. If the request's If-None-Match matches the stored ETag, weak (W/"…") or not, a 304 with no body. For the first page a hit still costs one round of indexer requests, the check that query's collection is unchanged, unless query checked it less than CACHE_MAX_AGE seconds ago.
• Miss or expired: items are read through query, the document is generated, stored, and returned with X-Cache: MISS.
• Cache off: every request generates the document. Responses carry an ETag and Last-Modified, but a matching If-None-Match still gets a 200.

The first page's ETag comes from query's collection ETag, the site config and the cacheBust value, so it stays the same across rebuilds of an unchanged feed. Later pages' and archives' come from the document.

Other things to know:

• Cache-Control is public, max-age=<n>, s-maxage=<n>, must-revalidate, with or without the cache: CACHE_MAX_AGE (default 0) for the first page, 3600 for later pages and 86400 for archives, whatever the TTLs are.
• When generation fails (the indexer is down, say), the handlers serve a cached document that hasn't expired and was built for the same site config, with X-Cache: STALE and Warning: 110 - "Response is stale". Since 0.7.12 each entry records its site config, so an entry cached before the upgrade isn't served stale until it has been rebuilt. An expired entry is deleted when it's read, so with nothing unexpired the response is a 500. Later pages and archives serve an unexpired entry as a hit before generation starts, so for them a failure usually ends in the 500.
• Feed and query share CACHE_DIR. Add it to .gitignore.
• With the cache off, the handlers log Cache is DISABLED once, when the first request creates the cache manager. Per-request logs (hits, misses, item counts, image probes) print only with DEBUG=seedFeed.

Related

• Serve published items as a feed: the walkthrough
• createFeed and handlers: the generation API, routes, field mapping and types
• Hyper distribution: @seedprotocol/feed-hyper and the seed-feed command
• @seedprotocol/query: how items are read and cached
• @seedprotocol/arweave and @seedprotocol/eas: gateway and chain settings