rss-parser

library2.1.1jsnpmunverified

rss-parser is a lightweight JavaScript library designed to convert RSS (and Atom) XML feeds into easily consumable JavaScript objects. It supports both Node.js environments and modern web browsers (with bundlers or pre-built distributions). The current stable version is 3.13.0, indicating active maintenance and regular updates. Key differentiators include its flexibility with both callback and Promise-based APIs, robust TypeScript support allowing custom field definitions for type safety, and the ability to parse either directly from a URL or an XML string. It provides a standardized output format, mapping common feed elements and offering a `contentSnippet` for HTML-stripped content. A notable consideration for browser usage is the need for a CORS proxy due to browser security restrictions on cross-origin requests.

http-networking serialization

npm install rss-parser

github ↗package ↗

INSTALL

IMPORT

SIG · RSS-PARSER

rss-parser

http-networkingjavascriptv2.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ import Parser from 'rss-parser';

✗ import { Parser } from 'rss-parser';

The primary class, `Parser`, is a default export. Use named import in CommonJS for older Node versions or if you encounter issues: `const Parser = require('rss-parser');`

ParserOptions

✓ import type { ParserOptions } from 'rss-parser';

✗ import { ParserOptions } from 'rss-parser';

Type imports for configuration options should use `import type` for clarity and bundler optimization, especially in TypeScript environments.

Item

✓ import type { Item } from 'rss-parser';

✗ import { Item } from 'rss-parser';

Types like `Item` (for individual feed entries) or `Output` (for the overall feed structure) are available for precise type annotations with `import type`.

This quickstart demonstrates parsing an RSS feed from a URL, including custom type definitions for additional feed and item fields, error handling, and considerations for CORS proxies in browser environments. It showcases `async/await` syntax for promise resolution.

import Parser from 'rss-parser'; type CustomFeed = { feedId?: string }; type CustomItem = { authorName?: string }; const parser: Parser<CustomFeed, CustomItem> = new Parser({ customFields: { feed: ['feedId'], item: ['authorName'] }, // Headers are crucial for some feeds, e.g., to mimic a browser request headers: { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36' } }); (async () => { try { // Use a CORS proxy for browser environments if fetching cross-origin const CORS_PROXY = process.env.CORS_PROXY ?? 'https://api.allorigins.win/get?url='; const feedUrl = 'https://www.reddit.com/.rss'; const urlToFetch = feedUrl.startsWith('http') ? CORS_PROXY + encodeURIComponent(feedUrl) : feedUrl; const feed = await parser.parseURL(urlToFetch); console.log(`Feed Title: ${feed.title}`); console.log(`Custom Feed ID: ${feed.feedId ?? 'N/A'}`); feed.items.forEach(item => { console.log(`- ${item.title ?? 'No Title'} by ${item.authorName ?? item.creator ?? 'Unknown'} (Link: ${item.link ?? 'N/A'})`); }); } catch (error) { console.error('Error parsing RSS feed:', error); } })();

Debug

Known issues

breakingThe `parseFile` method was removed in v3 for better browser compatibility. If you need to parse local files in Node.js, you'll first need to read the file content into a string and then use `parser.parseString()`.

fix

Read file content using `fs.readFile` or `fs.promises.readFile` and pass the string to `parser.parseString(fileContent)`.

affects: >=3.0.0

breakingIn v3, `Parser` must be instantiated using `new Parser()` before calling `parseString` or `parseURL`. Global static methods are no longer available.

fix

Change `Parser.parseURL(...)` to `const parser = new Parser(); parser.parseURL(...)`.

affects: >=3.0.0

breakingOptions are now passed to the `Parser` constructor (`new Parser(options)`) rather than as arguments to `parseURL` or `parseString` methods.

fix

Move all configuration options (e.g., `customFields`, `maxRedirects`) into the `new Parser({...})` constructor object.

affects: >=3.0.0

breakingThe top-level `parsed.feed` object was removed in v3. All feed properties are now directly accessible on the returned `feed` object (e.g., `feed.title` instead of `parsed.feed.title`).

fix

Remove the `.feed` accessor from the parsed object; directly access properties like `feed.title` and `feed.items`.

affects: >=3.0.0

breakingThe property for feed entries was renamed from `feed.entries` to `feed.items` in v3 to better align with common RSS XML terminology.

fix

Update all code referencing `feed.entries` to `feed.items`.

affects: >=3.0.0

gotchaWhen using `rss-parser` in a browser environment, direct requests to RSS feed URLs will often fail due to Cross-Origin Resource Sharing (CORS) security policies. The browser prevents fetching content from a different domain.

fix

You must use a CORS proxy to fetch the RSS feed. Examples include `https://cors-anywhere.herokuapp.com/` or `https://api.allorigins.win/get?url=` which forward the request and return the content with appropriate CORS headers.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Parser.parseURL is not a function

Attempting to call `parseURL` or `parseString` as a static method on the `Parser` class without first instantiating it, which was a breaking change in v3.

fix

Initialize the parser first: `const parser = new Parser();` and then call `parser.parseURL(...)`.

Access to fetch at 'https://example.com/feed.xml' from origin 'http://localhost:8080' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Attempting to fetch an RSS feed directly from a different domain in a browser environment without a CORS proxy.

fix

Route your `parseURL` request through a CORS proxy service, e.g., `parser.parseURL('https://cors-anywhere.herokuapp.com/' + 'https://example.com/feed.xml', ...)`.

Property 'someCustomField' does not exist on type 'CustomFeed'. Did you forget to include 'someCustomField' in your customFields configuration?

In TypeScript, a custom field was defined in a `CustomFeed` or `CustomItem` type but was not explicitly mapped in the `customFields` object passed to the `Parser` constructor.

fix

Ensure that every custom field defined in your TypeScript types (e.g., `CustomFeed`, `CustomItem`) is also listed in the `feed` or `item` array within the `customFields` option of the `Parser` constructor.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bobby-brennan/rss-parser ↗

packagehttps://www.npmjs.com/package/rss-parser ↗