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',
    // pull in the "site" from your project's astro.config
    site: import.meta.env.SITE,
    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',
  // provide a base URL for RSS <item> links
  site: import.meta.env.SITE,
  // 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/' },
});

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.

site

Type: string (required)

The base URL to use when generating RSS item links. We recommend using import.meta.env.SITE to pull in the "site" from your project's astro.config. Still, feel free to use a custom base URL if necessary.

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;
	/** Full content of the item, should be valid HTML */
	content?: 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/"...

---

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