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
NamespacesAtom, Dublin Core, Syndication, Content, Slash, iTunes, Podcast Index, RawVoice, Podlove Simple Chapters, Google Play Podcast, Spotify, Media RSS, W3C Basic Geo, GeoRSS Simple, Atom Threading, Dublin Core Terms, Comment API, Administrative, Pingback, Trackback, Source, ccREL, Creative Commons, FeedPress, OpenSearch

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, {
  lenient: true,
  stylesheets: [{ type: 'text/xsl', href: '/feed.xsl' }]
})

Parameters ​

ParameterTypeDescription
dataobjectRSS feed data to generate
optionsobjectOptional generation settings

Options ​

OptionTypeDefaultDescription
lenientbooleanfalseEnable lenient mode for relaxed validation, see Lenient 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/types'

// 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

TDate represents date fields in the type definitions. When parsing, dates are returned as strings in their original format (see Parsing › Handling Dates for more details). When generating, dates should be provided as JavaScript Date objects.

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 = {
    name: string
    domain?: string
  }

  export type Cloud = {
    domain: string
    port: number
    path: string
    registerProcedure: string
    protocol: string
  }

  export type Image = {
    url: string
    title: string
    link: string
    description?: string
    height?: number
    width?: number
  }

  export type TextInput = {
    title: string
    description: string
    name: string
    link: string
  }

  export type Enclosure = {
    url: string
    length: number
    type: string
  }

  export type SkipHours = Array<number>

  export type SkipDays = Array<string>

  export type Guid = {
    value: string
    isPermaLink?: boolean
  }

  export type Source = {
    title: string
    url?: string
  }

  export type Item<TDate extends DateLike, TPerson extends PersonLike = Person> = {
    title?: string
    link?: string
    description?: string
    authors?: Array<TPerson>
    categories?: Array<Category>
    comments?: string
    enclosures?: Array<Enclosure>
    guid?: Guid
    pubDate?: TDate
    source?: Source
    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
    psc?: PscNs.Item
    googleplay?: GooglePlayNs.Item
    media?: MediaNs.ItemOrFeed
    georss?: GeoRssNs.ItemOrFeed
    geo?: GeoNs.ItemOrFeed
    thr?: ThrNs.Item
    dcterms?: DcTermsNs.ItemOrFeed<TDate>
    wfw?: WfwNs.Item
    sourceNs?: SourceNs.Item
    rawvoice?: RawVoiceNs.Item
    spotify?: SpotifyNs.Item
    pingback?: PingbackNs.Item
    trackback?: TrackbackNs.Item
  } & ({ title: string } | { description: string })

  export type Feed<TDate extends DateLike, TPerson extends PersonLike = Person> = {
    title: string
    // INFO: Spec mentions required "link", but the "link" might be missing as well when the
    // atom:link rel="self" is present so that's why the "link" is not required in this type.
    link?: string
    description: string
    language?: string
    copyright?: string
    managingEditor?: TPerson
    webMaster?: TPerson
    pubDate?: TDate
    lastBuildDate?: TDate
    categories?: Array<Category>
    generator?: string
    docs?: string
    cloud?: Cloud
    ttl?: number
    image?: Image
    rating?: string
    textInput?: TextInput
    skipHours?: Array<number>
    skipDays?: Array<string>
    items?: Array<Item<TDate, TPerson>>
    atom?: AtomNs.Feed<TDate>
    cc?: CcNs.ItemOrFeed
    dc?: DcNs.ItemOrFeed<TDate>
    sy?: SyNs.Feed<TDate>
    itunes?: ItunesNs.Feed
    podcast?: PodcastNs.Feed<TDate>
    googleplay?: GooglePlayNs.Feed
    media?: MediaNs.ItemOrFeed
    georss?: GeoRssNs.ItemOrFeed
    geo?: GeoNs.ItemOrFeed
    dcterms?: DcTermsNs.ItemOrFeed<TDate>
    creativeCommons?: CreativeCommonsNs.ItemOrFeed
    feedpress?: FeedPressNs.Feed
    opensearch?: OpenSearchNs.Feed
    admin?: AdminNs.Feed
    sourceNs?: SourceNs.Feed
    rawvoice?: RawVoiceNs.Feed<TDate>
    spotify?: SpotifyNs.Feed
    pingback?: PingbackNs.Feed
  }
}