astro/packages/astro-rss/README.md

@astrojs/rss 📖

This package brings fast RSS feed generation to blogs and other content sites built with Astro. For more information about RSS feeds in general, see aboutfeeds.com.

Installation

Install the @astrojs/rss package into any Astro project using your preferred package manager:

# npm
npm i @astrojs/rss
# yarn
yarn add @astrojs/rss
# pnpm
pnpm i @astrojs/rss

Example usage

The @astrojs/rss package provides helpers for generating RSS feeds within Astro endpoints. This unlocks both static builds and on-demand generation when using an SSR adapter.

For instance, say you need to generate an RSS feed for all posts under src/pages/blog/. Start by adding a site to your project's astro.config for link generation. Then, create an rss.xml.js file under your project's src/pages/ directory, and use Vite's import.meta.glob helper like so:

// src/pages/rss.xml.js
import rss from '@astrojs/rss';

export const get = () => rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    items: import.meta.glob('./blog/**/*.md'),
  });

Read Astro's RSS docs for full usage examples.

rss() configuration options

The rss default export offers a number of configuration options. Here's a quick reference:

rss({
  // `<title>` field in output xml
  title: 'Buzz’s Blog',
  // `<description>` field in output xml
  description: 'A humble Astronaut’s guide to the stars',
  // list of `<item>`s in output xml
  items: import.meta.glob('./**/*.md'),
  // (optional) absolute path to XSL stylesheet in your project
  stylesheet: '/rss-styles.xsl',
  // (optional) inject custom xml
  customData: '<language>en-us</language>',
  // (optional) add arbitrary metadata to opening <rss> tag
  xmlns: { h: 'http://www.w3.org/TR/html4/' },
  // (optional) provide a canonical URL
  // defaults to the "site" configured in your project's astro.config
  canonicalUrl: 'https://stargazers.club',
});

title

Type: string (required)

The <title> attribute of your RSS feed's output xml.

description

Type: string (required)

The <description> attribute of your RSS feed's output xml.

items

Type: RSSFeedItem[] | GlobResult (required)

Either a list of formatted RSS feed items or the result of Vite's import.meta.glob helper. See Astro's RSS items documentation for usage examples to choose the best option for you.

When providing a formatted RSS item list, see the RSSFeedItem type reference below:

type RSSFeedItem = {
	/** Link to item */
	link: string;
	/** Title of item */
	title: string;
	/** Publication date of item */
	pubDate: Date;
	/** Item description */
	description?: string;
	/** Append some other XML-valid data to this item */
	customData?: string;
};

stylesheet

Type: string (optional)

An absolute path to an XSL stylesheet in your project. If you don’t have an RSS stylesheet in mind, we recommend the Pretty Feed v3 default stylesheet, which you can download from GitHub and save into your project's public/ directory.

customData

Type: string (optional)

A string of valid XML to be injected between your feed's <description> and <item> tags. This is commonly used to set a language for your feed:

import rss from '@astrojs/rss';

export const get = () => rss({
    ...
    customData: '<language>en-us</language>',
  });

xmlns

Type: Record<string, string> (optional)

An object mapping a set of xmlns suffixes to strings of metadata on the opening <rss> tag.

For example, this object:

rss({
  ...
  xmlns: { h: 'http://www.w3.org/TR/html4/' },
})

Will inject the following XML:

<rss xmlns:h="http://www.w3.org/TR/html4/"...

canonicalUrl

Type: string (optional)

The base URL to use when generating RSS item links. This defaults to the site configured in your project's astro.config. We recommend using site instead of canonicalUrl, though we provide this option if an override is necessary.

For more on building with Astro, visit the Astro docs.