Generating Feeds

Comprehensive guide to generating RSS/Atom feeds with rss.Today.

Feed Class Overview

The Feed class provides a builder pattern for creating feeds:


import { Feed } from 'rss.today';
 
const feed = new Feed(options);

Feed Options

Required Fields


{
  id: string;        // Unique identifier
  title: string;     // Feed title
  copyright: string; // Copyright notice
}

Optional Fields


{
  description?: string;  // Feed description
  link?: string;         // Website URL
  language?: string;     // Language code (e.g., 'en')
  updated?: Date;        // Last updated date
  generator?: string;    // Generator name
  ttl?: number;          // Time to live (minutes)
  feed?: string;         // Feed URL
  feedLinks?: any;       // Alternative feed links
  hub?: string;          // PubSubHubbub hub URL
  docs?: string;         // Documentation URL
  podcast?: boolean;     // Mark as podcast
  category?: string;     // Feed category
  author?: Author;      // Feed author
  image?: string;        // Feed image URL
  favicon?: string;      // Favicon URL
}

Author Interface


interface Author {
  name?: string;   // Author name
  email?: string;  // Author email
  link?: string;   // Author website
  avatar?: string; // Author avatar URL
}

Creating a Basic Feed


import { Feed } from 'rss.today';
 
const feed = new Feed({
  id: 'https://example.com/feed',
  title: 'My Tech Blog',
  description: 'A blog about technology and programming',
  link: 'https://example.com',
  copyright: '2024 My Tech Blog',
  language: 'en',
  updated: new Date()
});
 
// Add items
feed.addItem({
  title: 'Getting Started with TypeScript',
  link: 'https://example.com/typescript-intro',
  description: 'An introduction to TypeScript basics',
  date: new Date('2024-01-15')
});
 
// Generate RSS 2.0
const rss = feed.rss2();
console.log(rss);

Adding Items

Basic Item


feed.addItem({
  title: string;      // Required
  link: string;       // Required
  date: Date;         // Required
});

Complete Item


feed.addItem({
  // Core fields
  title: string;
  id?: string;
  link: string;
  date: Date;
 
  // Content fields
  description?: string;  // Plain text description
  content?: string;      // HTML content
  category?: Category[]; // Categories
 
  // Identifier
  guid?: string;         // Global unique identifier
 
  // Media
  image?: string | Enclosure;
  audio?: string | Enclosure;
  video?: string | Enclosure;
  enclosure?: Enclosure;
 
  // People
  author?: Author[];
  contributor?: Author[];
 
  // Metadata
  published?: Date;
  copyright?: string;
 
  // Extensions
  extensions?: Extension[];
});

Category Interface


interface Category {
  name?: string;   // Category name
  domain?: string; // Domain (RSS)
  scheme?: string; // Scheme (Atom)
  term?: string;   // Term (Atom)
}

Enclosure Interface


interface Enclosure {
  url: string;       // Media URL (required)
  type?: string;     // MIME type
  length?: number;   // Size in bytes
  title?: string;    // Title
  duration?: number;  // Duration in seconds (podcast)
}

Extension Interface


interface Extension {
  name: string;  // Extension name
  objects: any;  // Extension data
}

Adding Feed Components

Add Categories


feed.addCategory('technology');
feed.addCategory('programming');
feed.addCategory('web-development');

Add Contributors


feed.addContributor({
  name: 'Jane Doe',
  email: 'jane@example.com',
  link: 'https://example.com/jane'
});
 
feed.addContributor({
  name: 'John Smith',
  email: 'john@example.com'
});

Add Extensions


// iTunes extension
feed.addExtension({
  name: 'itunes',
  objects: {
    author: 'Podcast Author',
    summary: 'A podcast about technology',
    explicit: 'no',
    keywords: 'tech,programming,coding',
    image: 'https://example.com/podcast.jpg',
    owner: {
      name: 'Owner Name',
      email: 'owner@example.com'
    }
  }
});
 
// Custom extension
feed.addExtension({
  name: 'custom:namespace',
  objects: {
    'custom:field': 'value'
  }
});

Generating Different Formats

RSS 2.0


const rss2 = feed.rss2();

Most common format, widely supported by feed readers.

Atom 1.0


const atom1 = feed.atom1();

Modern alternative to RSS, uses XML namespaces.

RSS 1.0


const rss1 = feed.rss1();

RDF-based RSS format, less common.

RSS 0.9


const rss09 = feed.rss0_9();

Original RSS format, legacy support.

JSON Feed 1.0


const json1 = feed.json1();

JSON-based feed format, modern and developer-friendly.

Complete Examples

Blog Feed


import { Feed } from 'rss.today';
 
const feed = new Feed({
  id: 'https://example.com/feed',
  title: 'My Tech Blog',
  description: 'A blog about technology and programming',
  link: 'https://example.com',
  feed: 'https://example.com/feed.xml',
  language: 'en',
  copyright: '2024 My Tech Blog',
  updated: new Date(),
  generator: 'rss.Today',
  author: {
    name: 'Blog Author',
    email: 'author@example.com',
    link: 'https://example.com/author'
  },
  image: 'https://example.com/logo.png',
  favicon: 'https://example.com/favicon.ico'
});
 
// Add blog posts
feed.addItem({
  title: 'Introduction to TypeScript',
  id: 'https://example.com/typescript-intro',
  link: 'https://example.com/typescript-intro',
  description: 'Learn the basics of TypeScript',
  content: '<p>TypeScript is a typed superset of JavaScript...</p>',
  date: new Date('2024-01-15'),
  author: [{
    name: 'Blog Author',
    email: 'author@example.com'
  }],
  category: [
    { name: 'TypeScript' },
    { name: 'JavaScript' }
  ],
  published: new Date('2024-01-15')
});
 
feed.addItem({
  title: 'Getting Started with Node.js',
  id: 'https://example.com/nodejs-intro',
  link: 'https://example.com/nodejs-intro',
  description: 'Learn Node.js basics',
  content: '<p>Node.js is a JavaScript runtime...</p>',
  date: new Date('2024-01-20'),
  author: [{
    name: 'Blog Author',
    email: 'author@example.com'
  }],
  category: [
    { name: 'Node.js' },
    { name: 'Backend' }
  ],
  published: new Date('2024-01-20')
});
 
// Generate all formats
const rss2 = feed.rss2();
const atom1 = feed.atom1();
const json1 = feed.json1();

Podcast Feed


import { Feed } from 'rss.today';
 
const feed = new Feed({
  id: 'https://example.com/podcast',
  title: 'Tech Talk Podcast',
  description: 'Weekly discussions about technology',
  link: 'https://example.com',
  feed: 'https://example.com/podcast.xml',
  language: 'en',
  copyright: '2024 Tech Talk',
  updated: new Date(),
  podcast: true,
  category: 'Technology',
  author: {
    name: 'Tech Talk Host',
    email: 'host@example.com'
  },
  image: 'https://example.com/podcast-cover.jpg'
});
 
// Add iTunes extensions
feed.addExtension({
  name: 'itunes',
  objects: {
    author: 'Tech Talk Host',
    subtitle: 'Weekly tech discussions',
    summary: 'Join us every week for discussions about the latest in technology, programming, and software development.',
    explicit: 'clean',
    keywords: 'technology,programming,software,development',
    image: 'https://example.com/podcast-cover.jpg',
    owner: {
      name: 'Tech Talk Host',
      email: 'host@example.com'
    },
    categories: [
      'Technology',
      'Software How-To'
    ]
  }
});
 
// Add episodes
feed.addItem({
  title: 'Episode 1: Introduction to React',
  link: 'https://example.com/episode-1',
  description: 'Learn the basics of React framework',
  date: new Date('2024-01-01'),
  enclosure: {
    url: 'https://example.com/episode-1.mp3',
    type: 'audio/mpeg',
    length: 15728640  // 15MB
  },
  category: [{ name: 'React' }]
});
 
feed.addItem({
  title: 'Episode 2: TypeScript Deep Dive',
  link: 'https://example.com/episode-2',
  description: 'Advanced TypeScript techniques',
  date: new Date('2024-01-08'),
  enclosure: {
    url: 'https://example.com/episode-2.mp3',
    type: 'audio/mpeg',
    length: 17825792  // 17MB
  },
  category: [{ name: 'TypeScript' }]
});
 
const rss2 = feed.rss2();

News Feed with Media


import { Feed } from 'rss.today';
 
const feed = new Feed({
  id: 'https://news.example.com/feed',
  title: 'Daily News',
  description: 'Breaking news and updates',
  link: 'https://news.example.com',
  feed: 'https://news.example.com/feed.xml',
  language: 'en',
  copyright: '2024 Daily News',
  updated: new Date(),
  image: 'https://news.example.com/logo.png'
});
 
// Add news articles with images
feed.addItem({
  title: 'Breaking: New Technology Announced',
  link: 'https://news.example.com/article-1',
  description: 'A groundbreaking new technology has been announced',
  content: '<p>Full article content...</p>',
  date: new Date(),
  image: {
    url: 'https://news.example.com/images/article-1.jpg',
    type: 'image/jpeg',
    length: 524288
  },
  author: [{
    name: 'John Reporter',
    email: 'john@news.example.com'
  }],
  category: [{ name: 'Technology' }]
});
 
// Add video content
feed.addItem({
  title: 'Video Report: Tech Conference',
  link: 'https://news.example.com/video-1',
  description: 'Watch the highlights from the tech conference',
  date: new Date(),
  video: {
    url: 'https://news.example.com/videos/conference.mp4',
    type: 'video/mp4',
    length: 52428800  // 50MB
  },
  author: [{
    name: 'Jane Reporter',
    email: 'jane@news.example.com'
  }],
  category: [{ name: 'Events' }]
});
 
const rss2 = feed.rss2();

Best Practices

Use Consistent Dates


feed.addItem({
  title: 'Post Title',
  link: 'https://example.com/post',
  date: new Date(),      // Item date
  published: new Date()  // Published date (optional)
});

Include Essential Metadata


const feed = new Feed({
  id: 'https://example.com/feed',
  title: 'Feed Title',
  link: 'https://example.com',
  copyright: 'Copyright 2024',
  language: 'en',
  updated: new Date()  // Important for feed readers
});

Use Enclosures for Media


feed.addItem({
  title: 'Audio Episode',
  link: 'https://example.com/episode',
  date: new Date(),
  enclosure: {
    url: 'https://example.com/audio.mp3',
    type: 'audio/mpeg',
    length: 15728640,  // Actual file size in bytes
    title: 'Episode Title',
    duration: 3600     // Duration in seconds (1 hour)
  }
});

Add Categories for Better Organization


feed.addItem({
  title: 'Post',
  link: 'https://example.com/post',
  date: new Date(),
  category: [
    { name: 'Technology' },
    { name: 'Web Development' },
    { name: 'JavaScript' }
  ]
});