Feedsmith

RSS Feed Reference ​

RSS (Really Simple Syndication) is one of the most widely used web feed formats. Feedsmith automatically normalizes legacy elements to their modern equivalents.

Versions0.9x, 2.0
SpecificationRSS 2.0 Specification
NamespacesAtom, Dublin Core, Dublin Core Terms, Syndication, Content, Slash, iTunes, Podcast Index, Podlove Simple Chapters, Media RSS, Google Play Podcast, Spotify, Acast, RawVoice, FeedBurner, FeedPress, arXiv, OpenSearch, PRISM, ccREL, Creative Commons, Atom Threading, Comment API, Administrative, Pingback, Trackback, Source, blogChannel, W3C Basic Geo, GeoRSS Simple, XML

Functions ​

parseRssFeed() ​

Parses RSS feed content and returns a typed RSS object.

typescript
import { parseRssFeed } from 'feedsmith'

const rssFeed = parseRssFeed(xmlContent)
// Returns: object with all fields optional and dates as strings

// Limit number of items parsed
const rssFeed = parseRssFeed(xmlContent, { maxItems: 10 })

Parameters ​

ParameterTypeDescription
contentstringThe RSS XML content to parse
optionsobjectOptional parsing settings

Options ​

OptionTypeDefaultDescription
maxItemsnumber-Limit the number of items parsed. Use 0 to skip items entirely, useful when only feed metadata is needed

Returns ​

object - Parsed RSS feed with all fields optional and dates as strings

generateRssFeed() ​

Generates RSS XML from feed data.

typescript
import { generateRssFeed } from 'feedsmith'

const xml = generateRssFeed(feedData, {
  stylesheets: [{ type: 'text/xsl', href: '/feed.xsl' }]
})

Parameters ​

ParameterTypeDescription
dataobjectRSS feed data to generate
optionsobjectOptional generation settings

Options ​

OptionTypeDefaultDescription
strictbooleanfalseEnable strict mode for spec-required field validation, see Strict Mode
stylesheetsStylesheet[]-Add stylesheets for visual formatting, see Feed Styling

Returns ​

string - Generated RSS XML

detectRssFeed() ​

Detects if the provided content is an RSS feed.

Parameters ​

ParameterTypeDescription
contentstringThe content to check

Returns ​

boolean - true if content appears to be RSS format

Example ​

typescript
import { detectRssFeed } from 'feedsmith'

const isRss = detectRssFeed(xmlContent)

Types ​

All RSS types are available under the RssFeed namespace:

typescript
import type { RssFeed } from 'feedsmith'

// Access any type from the definitions below
type Feed = RssFeed.Feed<Date>
type Item = RssFeed.Item<Date>
type Category = RssFeed.Category
type Enclosure = RssFeed.Enclosure
// … see type definitions below for all available types

See the TypeScript guide for usage examples.

Type Definitions ​

INFO

For details on type parameters (TDate, TStrict) and Requirable<T> markers, see TypeScript Reference.

ts
export namespace RssFeed {
  export type Person = {
    name?: string
    email?: string
    // Parse-only. Extracted from URLs found in person strings. Not included in generated output, as
    // the RSS spec has no standard way to encode links in person fields.
    link?: string
  }

  export type Category<TStrict extends boolean = false> = Strict<
    {
      name: Requirable<string> // Required in spec
      domain?: string
    },
    TStrict
  >

  export type Cloud<TStrict extends boolean = false> = Strict<
    {
      domain: Requirable<string> // Required in spec
      port: Requirable<number> // Required in spec
      path: Requirable<string> // Required in spec
      registerProcedure: Requirable<string> // Required in spec
      protocol: Requirable<string> // Required in spec
    },
    TStrict
  >

  export type Image<TDate, TStrict extends boolean = false> = Strict<
    {
      url: Requirable<string> // Required in spec
      title: Requirable<string> // Required in spec
      link: Requirable<string> // Required in spec
      description?: string
      height?: number
      width?: number
      prism?: PrismNs.ItemOrFeed<TDate>
      cc?: CcNs.ItemOrFeed
    },
    TStrict
  >

  export type TextInput<TDate, TStrict extends boolean = false> = Strict<
    {
      title: Requirable<string> // Required in spec
      description: Requirable<string> // Required in spec
      name: Requirable<string> // Required in spec
      link: Requirable<string> // Required in spec
      prism?: PrismNs.ItemOrFeed<TDate>
    },
    TStrict
  >

  export type Enclosure<TStrict extends boolean = false> = Strict<
    {
      url: Requirable<string> // Required in spec
      length: Requirable<number> // Required in spec
      type: Requirable<string> // Required in spec
    },
    TStrict
  >

  export type SkipHours = Array<number>

  export type SkipDays = Array<string>

  export type Guid<TStrict extends boolean = false> = Strict<
    {
      value: Requirable<string> // Required in spec
      isPermaLink?: boolean
    },
    TStrict
  >

  export type Source<TStrict extends boolean = false> = Strict<
    {
      title: Requirable<string> // Required in spec
      url: Requirable<string> // Required in spec
    },
    TStrict
  >

  export type Item<TDate, TStrict extends boolean = false> = Strict<
    {
      title?: string // At least one of title or description is required in spec
      link?: string
      description?: string // At least one of title or description is required in spec
      authors?: Array<Person>
      categories?: Array<Category<TStrict>>
      comments?: string
      enclosures?: Array<Enclosure<TStrict>>
      guid?: Guid<TStrict>
      pubDate?: TDate
      expirationDate?: TDate
      source?: Source<TStrict>
      atom?: AtomNs.Entry<TDate>
      dc?: DcNs.ItemOrFeed<TDate>
      dcterms?: DcTermsNs.ItemOrFeed<TDate>
      content?: ContentNs.Item
      slash?: SlashNs.Item
      itunes?: ItunesNs.Item
      podcast?: PodcastNs.Item<TStrict>
      psc?: PscNs.Item<TStrict>
      media?: MediaNs.ItemOrFeed<TStrict>
      googleplay?: GooglePlayNs.Item<TStrict>
      spotify?: SpotifyNs.Item<TStrict>
      acast?: AcastNs.Item
      rawvoice?: RawVoiceNs.Item<TStrict>
      feedburner?: FeedBurnerNs.Item
      arxiv?: ArxivNs.Entry
      prism?: PrismNs.ItemOrFeed<TDate>
      cc?: CcNs.ItemOrFeed
      creativeCommons?: CreativeCommonsNs.ItemOrFeed
      thr?: ThrNs.Item<TStrict>
      wfw?: WfwNs.Item
      pingback?: PingbackNs.Item
      trackback?: TrackbackNs.Item
      sourceNs?: SourceNs.Item<TStrict>
      geo?: GeoNs.ItemOrFeed
      georss?: GeoRssNs.ItemOrFeed<TStrict>
      xml?: XmlNs.ItemOrFeed
    },
    TStrict
  > &
    (TStrict extends true ? { title: string } | { description: string } : unknown)

  export type Feed<TDate, TStrict extends boolean = false> = Strict<
    {
      title: Requirable<string> // Required in spec
      link: Requirable<string> // Required in spec (but may be missing when atom:link rel="self" is present)
      description: Requirable<string> // Required in spec
      language?: string
      copyright?: string
      managingEditor?: Person
      webMaster?: Person
      pubDate?: TDate
      lastBuildDate?: TDate
      categories?: Array<Category<TStrict>>
      generator?: string
      docs?: string
      cloud?: Cloud<TStrict>
      ttl?: number
      image?: Image<TDate, TStrict>
      rating?: string
      textInput?: TextInput<TDate, TStrict>
      skipHours?: Array<number>
      skipDays?: Array<string>
      items?: Array<Item<TDate, TStrict>>
      atom?: AtomNs.Feed<TDate>
      dc?: DcNs.ItemOrFeed<TDate>
      dcterms?: DcTermsNs.ItemOrFeed<TDate>
      sy?: SyNs.Feed<TDate>
      itunes?: ItunesNs.Feed<TStrict>
      podcast?: PodcastNs.Feed<TDate, TStrict>
      media?: MediaNs.ItemOrFeed<TStrict>
      googleplay?: GooglePlayNs.Feed<TStrict>
      spotify?: SpotifyNs.Feed<TStrict>
      acast?: AcastNs.Feed
      rawvoice?: RawVoiceNs.Feed<TDate, TStrict>
      feedburner?: FeedBurnerNs.Feed<TStrict>
      feedpress?: FeedPressNs.Feed
      opensearch?: OpenSearchNs.Feed<TStrict>
      prism?: PrismNs.ItemOrFeed<TDate>
      cc?: CcNs.ItemOrFeed
      creativeCommons?: CreativeCommonsNs.ItemOrFeed
      admin?: AdminNs.Feed
      pingback?: PingbackNs.Feed
      sourceNs?: SourceNs.Feed<TStrict>
      blogChannel?: BlogChannelNs.Feed
      geo?: GeoNs.ItemOrFeed
      georss?: GeoRssNs.ItemOrFeed<TStrict>
      xml?: XmlNs.ItemOrFeed
    },
    TStrict
  >
}