Quick Start

This guide will get you up and running with Feedsmith in just a few minutes.

Installation

Feedsmith works in both Node.js (14.0.0+) and modern browsers, supporting both CommonJS and ES modules. It was tested in both environments, ensuring compatibility and reliability.

Install the package using your preferred package manager:

npm

npm install feedsmith

yarn

yarn add feedsmith

pnpm

pnpm add feedsmith

bun

bun add feedsmith

Or using CDN:

unpkg

<script type="module">
  import { parseFeed } from 'https://unpkg.com/feedsmith@latest/dist/index.js'

  const { format, feed } = parseFeed(feedContent)
  console.log(feed.title)
</script>

jsDelivr

<script type="module">
  import { parseFeed } from 'https://cdn.jsdelivr.net/npm/feedsmith@latest/dist/index.js'

  const { format, feed } = parseFeed(feedContent)
  console.log(feed.title)
</script>

esm.sh

<script type="module">
  import { parseFeed } from 'https://esm.sh/feedsmith@latest'

  const { format, feed } = parseFeed(feedContent)
  console.log(feed.title)
</script>

Parse Any Feed

The simplest way to parse any feed is to use the universal parseFeed function:

import { parseFeed } from 'feedsmith'

// Works with RSS, Atom, RDF, and JSON Feed
const { format, feed } = parseFeed(feedContent)

console.log('Feed format:', format) // rss, atom, json, rdf
console.log('Feed title:', feed.title)

if (format === 'rss') {
  console.log('RSS feed link:', feed.link)
}

Parse Specific Feed Formats

If you know the format in advance, you can use the format-specific parsers:

import {
  parseRssFeed,
  parseAtomFeed,
  parseRdfFeed,
  parseJsonFeed
} from 'feedsmith'

// Parse specific formats
const rssFeed = parseRssFeed('rss content')
const atomFeed = parseAtomFeed('atom content')
const rdfFeed = parseRdfFeed('rdf content')
const jsonFeed = parseJsonFeed('json content')

// Access typed data
rssFeed.title
rssFeed.dc?.creator
rssFeed.items?.[0]?.title

Parse OPML Files

Parsing OPML files is just as simple:

import { parseOpml } from 'feedsmith'

const opml = parseOpml('opml content')

opml.head?.title
opml.body?.outlines?.[0].text
opml.body?.outlines?.[1].xmlUrl

Generate a Feed

import { generateRssFeed } from 'feedsmith'

const rss = generateRssFeed({
  title: 'My Blog',
  link: 'https://example.com',
  description: 'A simple blog',
  items: [{
    title: 'Hello World',
    link: 'https://example.com/hello',
    description: 'My first post',
    pubDate: new Date()
  }]
})

console.log(rss) // Complete RSS XML

// You can also generate other formats:
// - generateAtomFeed() for Atom feeds
// - generateJsonFeed() for JSON feeds
// - generateOpml() for OPML files

Error Handling

If the feed is unrecognized or invalid, an Error will be thrown with a descriptive message.

import { parseFeed, parseJsonFeed } from 'feedsmith'

try {
  const universalFeed = parseFeed('<not-a-feed></not-a-feed>')
} catch (error) {
  // Error: Unrecognized feed format
}

try {
  const jsonFeed = parseJsonFeed('{}')
} catch (error) {
  // Error: Invalid feed format
}

TypeScript Types

Feedsmith provides comprehensive TypeScript types for all feed formats:

import type { Rss, Atom, Json, Opml } from 'feedsmith/types'

// Access all types for a format
type Feed = Rss.Feed
type Item = Rss.Item
type Category = Rss.Category
type Enclosure = Rss.Enclosure

Each format exports its complete type system, including nested types and namespace types. See the TypeScript guide for details.

What's Next?

• Parse feeds — Learn about parsing different formats
• Work with namespaces — Access podcast, media, and other metadata
• Generate feeds — Create feeds in various formats
• API Reference — Explore all available functions and types
• Benchmarks — See how Feedsmith compares to other libraries