@dawiidio/rss NPM

@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: 'john@magicbeasts.xyz'
            },
            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: 'john@magicbeasts.xyz'
            },
            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

rss itunes podcast rss2 xml parser

dayjs sanitize-html

@everything-registry/sub-chunk-225

0.1.0

1 year ago