Feedsmith

Appearance

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, FeedPress, 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 Rss namespace:

typescript
import type { Rss } from 'feedsmith'

// Access any type from the definitions below
type Feed = Rss.Feed<Date>
type Item = Rss.Item<Date>
type Category = Rss.Category
type Enclosure = Rss.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 Rss {
  /** @internal Intermediary type before Person refactoring. Do not use downstream. */
  export type PersonLike = string | { name?: string; email?: string }

  export type Person = 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<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
    },
    TStrict
  >

  export type TextInput<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.
    },
    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 extends DateLike,
    TPerson extends PersonLike = Person,
    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<TPerson>
      categories?: Array<Category<TStrict>>
      comments?: string
      enclosures?: Array<Enclosure<TStrict>>
      guid?: Guid<TStrict>
      pubDate?: TDate
      source?: Source<TStrict>
      atom?: AtomNs.Entry<TDate>
      cc?: CcNs.ItemOrFeed
      dc?: DcNs.ItemOrFeed<TDate>
      content?: ContentNs.Item
      creativeCommons?: CreativeCommonsNs.ItemOrFeed
      slash?: SlashNs.Item
      itunes?: ItunesNs.Item
      podcast?: PodcastNs.Item<TStrict>
      psc?: PscNs.Item<TStrict>
      googleplay?: GooglePlayNs.Item<TStrict>
      media?: MediaNs.ItemOrFeed<TStrict>
      georss?: GeoRssNs.ItemOrFeed<TStrict>
      geo?: GeoNs.ItemOrFeed
      thr?: ThrNs.Item<TStrict>
      dcterms?: DcTermsNs.ItemOrFeed<TDate>
      prism?: PrismNs.Item<TDate>
      wfw?: WfwNs.Item
      sourceNs?: SourceNs.Item
      rawvoice?: RawVoiceNs.Item<TStrict>
      spotify?: SpotifyNs.Item<TStrict>
      pingback?: PingbackNs.Item
      trackback?: TrackbackNs.Item
      acast?: AcastNs.Item
      xml?: XmlNs.ItemOrFeed
    },
    TStrict
  > &
    (TStrict extends true ? { title: string } | { description: string } : unknown)

  export type Feed<
    TDate extends DateLike,
    TPerson extends PersonLike = Person,
    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?: TPerson
      webMaster?: TPerson
      pubDate?: TDate
      lastBuildDate?: TDate
      categories?: Array<Category<TStrict>>
      generator?: string
      docs?: string
      cloud?: Cloud<TStrict>
      ttl?: number
      image?: Image<TStrict>
      rating?: string
      textInput?: TextInput<TStrict>
      skipHours?: Array<number>
      skipDays?: Array<string>
      items?: Array<Item<TDate, TPerson, TStrict>>
      atom?: AtomNs.Feed<TDate>
      cc?: CcNs.ItemOrFeed
      dc?: DcNs.ItemOrFeed<TDate>
      sy?: SyNs.Feed<TDate>
      itunes?: ItunesNs.Feed<TStrict>
      podcast?: PodcastNs.Feed<TDate, TStrict>
      googleplay?: GooglePlayNs.Feed<TStrict>
      media?: MediaNs.ItemOrFeed<TStrict>
      georss?: GeoRssNs.ItemOrFeed<TStrict>
      geo?: GeoNs.ItemOrFeed
      dcterms?: DcTermsNs.ItemOrFeed<TDate>
      prism?: PrismNs.Feed<TDate>
      creativeCommons?: CreativeCommonsNs.ItemOrFeed
      feedpress?: FeedPressNs.Feed
      opensearch?: OpenSearchNs.Feed<TStrict>
      admin?: AdminNs.Feed
      sourceNs?: SourceNs.Feed<TStrict>
      blogChannel?: BlogChannelNs.Feed
      rawvoice?: RawVoiceNs.Feed<TDate, TStrict>
      spotify?: SpotifyNs.Feed<TStrict>
      pingback?: PingbackNs.Feed
      acast?: AcastNs.Feed
      xml?: XmlNs.ItemOrFeed
    },
    TStrict
  >
}