@dawiidio/rss

Small library for quick rss endpoints development. It's just a syntax sugar for a few standards: raw RSS2, Apple podcast and Spotify podcast.

Installation

yarn add @dawiidio/rss
# or
npm install @dawiidio/rss

Usage

Basic example

import { createRssChannel, IChannelProps, createRendererForChannel, getRenderer } from '@dawiidio/rss';

const channel: IChannelProps = {
    title: 'My podcast',
    description: 'I will talk about unicorns and magic beasts',
    link: 'https://mypage.xyz/podcast',
    items: [
        {
            title: 'How I meet unicorn',
            description: 'Story about how I meet <strong>unicorn</strong> for the first time!',
            link: 'https://mypage.xyz/podcast/unicorn-story'
        },
    ]
};

const renderer = createRendererForChannel(getRenderer('xml'), channel);

console.log(renderer.render());

Basic podcast example (raw xml, see itunes below)

import { 
    createRssChannel, 
    IChannelProps,
    createRendererForChannel,
    getRenderer,
    parseToRSSDateFormat,
    megabytesToBytes
} from '@dawiidio/rss';

const channel: IChannelProps = {
    title: 'My podcast',
    description: 'I will talk about unicorns and magic beasts',
    link: 'https://magicbeasts.xyz/podcast',
    language: 'en-US',
    image: {
        url: 'https://magicbeasts.xyz/public/podcast-cover.jpg',
        title: 'Podcast cover',
        link: 'https://magicbeasts.xyz/podcast'
    },
    items: [
        {
            title: 'How I meet unicorn',
            description: 'Story about how I meet <strong>unicorn</strong> for the first time!',
            link: 'https://magicbeasts.xyz/podcast/unicorn-story',
            author: {
                name: 'John Doe',
                email: '[email protected]'
            },
            enclosure: {
                url: 'https://magicbeasts.xyz/public/unicorn-story.mp3',
                type: 'audio/mp3',
                length: megabytesToBytes(86) // file size in bytes
            },
            pubDate: parseToRSSDateFormat('21.02.2023')
        },
    ]
};

const renderer = createRendererForChannel(getRenderer('xml'), channel);

console.log(renderer.render());

Since Spotify and Apple are using additional tags for podcasts you can specify them in overrides field available on channel and item (episode) level.

import { 
    createRssChannel,
    IChannelProps,
    createRendererForChannel,
    getRenderer,
    megabytesToBytes,
    parseHMSToSeconds
} from '@dawiidio/rss';

const channel: IChannelProps = {
    title: 'My podcast',
    description: 'I will talk about unicorns and magic beasts',
    link: 'https://magicbeasts.xyz/podcast',
    language: 'en-US',
    image: {
        url: 'https://magicbeasts.xyz/public/podcast-cover.jpg',
        title: 'Podcast cover',
        link: 'https://magicbeasts.xyz/podcast'
    },
    items: [
        {
            title: 'How I meet unicorn',
            description: 'Story about how I meet <strong>unicorn</strong> for the first time!',
            link: 'https://magicbeasts.xyz/podcast/unicorn-story',
            author: {
                name: 'John Doe',
                email: '[email protected]'
            },
            enclosure: {
                url: 'https://magicbeasts.xyz/public/unicorn-story.mp3',
                type: 'audio/mp3',
                length: megabytesToBytes(125.5) // file size in bytes
            },
            overrides: {
                itunes: {
                    image: 'https://magicbeasts.xyz/public/unicorn-story-cover.jpg',
                    duration: parseHMSToSeconds('1:23:05')
                }
            }
        },
    ],
    overrides: {
        itunes: {
            title: 'This is a specific title only for Apple Podcast'
        }
    }
};

const renderer = createRendererForChannel(getRenderer('xml:itunes'), channel);

console.log(renderer.render());

Ui renderer

HTML renderer is also included by default in library, there are two methods to render html for rss,

first, simple with default settings

import { HtmlRss2Renderer, createRssChannel, IChannelProps, createRendererForChannel, getRenderer } from '@dawiidio/rss';

const renderer = createRendererForChannel(
    getRenderer('html'),
    channel
);

second, with options

import { HtmlRss2Renderer, createRssChannel, IChannelProps, createRendererForChannel, getRenderer } from '@dawiidio/rss';

const renderer = createRendererForChannel(
    new HtmlRss2Renderer({ cssClassPrefix: 'my prefix' }),
    channel
);

UiRenderer also has different api than base renderer

import { HtmlRss2Renderer, createRssChannel, IChannelProps, createRendererForChannel, getRenderer } from '@dawiidio/rss';

const renderer = createRendererForChannel(
    new HtmlRss2Renderer({ 
        cssClassPrefix: 'my-prefix-',
        trimEpisodeDescInListTo: 200
    }),
    channel
);

console.log(renderer.renderEpisodePage('episode guid')); // renders html for single item/episode
console.log(renderer.renderChannelPage({
    getPaginationUrl: (page, active) => `https://dawiid.io/podcast/${page}`,
    itemsPerPage: 20,
    offset: 0,
    activeItem: 0,
})); // renders page with list of items/episodes and pagination

Integrations

Examples of integration with frameworks and other libs

Remix

// src/routes/rss[.]xml.ts

And html renderer

// src/routes/podcast/$slug.ts

Custom renderers

You can add your own renderers by extending after Renderer class or UiRenderer.

Differences between Renderer and UiRenderer:

• Renderer is for formats not needing visual representation (like xml or json) because they are read by machines
• UiRenderer is for visual representation formats like html

For sample implementations look in src/renderer/xml and src/renderer/html folders

import { createRssChannel, Renderer } from '@dawiidio/rss';

class MyRenderer extends Renderer {
    // ...
}

const renderer = createRendererForChannel(new MyRenderer(), channel);

console.log(renderer.render());

Sources

• Apple podcaster's guide to RSS
• Raw RSS2 standard
• Spotify's resources for podcasters
• Apple's support post about podcast rss