{"id":13615637,"url":"https://github.com/rbren/rss-parser","last_synced_at":"2025-05-14T10:09:52.735Z","repository":{"id":2260830,"uuid":"46092465","full_name":"rbren/rss-parser","owner":"rbren","description":"A lightweight RSS parser, for Node and the browser","archived":false,"fork":false,"pushed_at":"2024-11-13T16:51:47.000Z","size":4945,"stargazers_count":1425,"open_issues_count":64,"forks_count":215,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-04T08:34:03.210Z","etag":null,"topics":["json","nodejs","rss","rss-feed","rss-parser","rss-reader","xml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rbren.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-11-13T01:38:55.000Z","updated_at":"2025-04-01T08:31:00.000Z","dependencies_parsed_at":"2024-12-12T09:01:19.988Z","dependency_job_id":"23a5c9f4-a422-42aa-aa59-9efb9ddbc236","html_url":"https://github.com/rbren/rss-parser","commit_stats":{"total_commits":308,"total_committers":62,"mean_commits":4.967741935483871,"dds":0.5227272727272727,"last_synced_commit":"e9b21691d25cc125c7a4d7be9835e318aee5bc70"},"previous_names":["bobby-brennan/rss-parser"],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbren%2Frss-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbren%2Frss-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbren%2Frss-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbren%2Frss-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rbren","download_url":"https://codeload.github.com/rbren/rss-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248420014,"owners_count":21100290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","nodejs","rss","rss-feed","rss-parser","rss-reader","xml"],"created_at":"2024-08-01T20:01:16.036Z","updated_at":"2025-04-11T14:38:22.867Z","avatar_url":"https://github.com/rbren.png","language":"JavaScript","readme":"# rss-parser\n\n[![Version][npm-image]][npm-link]\n[![Build Status][build-image]][build-link]\n[![Downloads][downloads-image]][npm-link]\n\n[downloads-image]: https://img.shields.io/npm/dm/rss-parser.svg\n[npm-image]: https://img.shields.io/npm/v/rss-parser.svg\n[npm-link]: https://npmjs.org/package/rss-parser\n[build-image]: https://github.com/rbren/rss-parser/workflows/tests/badge.svg\n[build-link]: https://github.com/rbren/rss-parser/actions\n\nA small library for turning RSS XML feeds into JavaScript objects.\n\n## Installation\n```bash\nnpm install --save rss-parser\n```\n\n## Usage\nYou can parse RSS from a URL (`parser.parseURL`) or an XML string (`parser.parseString`).\n\nBoth callbacks and Promises are supported.\n\n### NodeJS\nHere's an example in NodeJS using Promises with async/await:\n\n```js\nlet Parser = require('rss-parser');\nlet parser = new Parser();\n\n(async () =\u003e {\n\n  let feed = await parser.parseURL('https://www.reddit.com/.rss');\n  console.log(feed.title);\n\n  feed.items.forEach(item =\u003e {\n    console.log(item.title + ':' + item.link)\n  });\n\n})();\n```\n\n### TypeScript\nWhen using TypeScript, you can set a type to control the custom fields:\n\n```typescript\nimport Parser from 'rss-parser';\n\ntype CustomFeed = {foo: string};\ntype CustomItem = {bar: number};\n\nconst parser: Parser\u003cCustomFeed, CustomItem\u003e = new Parser({\n  customFields: {\n    feed: ['foo', 'baz'],\n    //            ^ will error because `baz` is not a key of CustomFeed\n    item: ['bar']\n  }\n});\n\n(async () =\u003e {\n  const parser = new Parser();\n  const feed = await parser.parseURL('https://www.reddit.com/.rss');\n  console.log(feed.title); // feed will have a `foo` property, type as a string\n\n  feed.items.forEach(item =\u003e {\n    console.log(item.title + ':' + item.link) // item will have a `bar` property type as a number\n  });\n})();\n```\n\n### Web\n\u003e We recommend using a bundler like [webpack](https://webpack.js.org/), but we also provide\n\u003e pre-built browser distributions in the `dist/` folder. If you use the pre-built distribution,\n\u003e you'll need a [polyfill](https://github.com/taylorhakes/promise-polyfill) for Promise support.\n\nHere's an example in the browser using callbacks:\n\n```html\n\u003cscript src=\"/node_modules/rss-parser/dist/rss-parser.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n\n// Note: some RSS feeds can't be loaded in the browser due to CORS security.\n// To get around this, you can use a proxy.\nconst CORS_PROXY = \"https://cors-anywhere.herokuapp.com/\"\n\nlet parser = new RSSParser();\nparser.parseURL(CORS_PROXY + 'https://www.reddit.com/.rss', function(err, feed) {\n  if (err) throw err;\n  console.log(feed.title);\n  feed.items.forEach(function(entry) {\n    console.log(entry.title + ':' + entry.link);\n  })\n})\n\n\u003c/script\u003e\n```\n\n### Upgrading from v2 to v3\nA few minor breaking changes were made in v3. Here's what you need to know:\n\n* You need to construct a `new Parser()` before calling `parseString` or `parseURL`\n* `parseFile` is no longer available (for better browser support)\n* `options` are now passed to the Parser constructor\n* `parsed.feed` is now just `feed` (top-level object removed)\n* `feed.entries` is now `feed.items` (to better match RSS XML)\n\n\n## Output\nCheck out the full output format in [test/output/reddit.json](test/output/reddit.json)\n\n```yaml\nfeedUrl: 'https://www.reddit.com/.rss'\ntitle: 'reddit: the front page of the internet'\ndescription: \"\"\nlink: 'https://www.reddit.com/'\nitems:\n    - title: 'The water is too deep, so he improvises'\n      link: 'https://www.reddit.com/r/funny/comments/3skxqc/the_water_is_too_deep_so_he_improvises/'\n      pubDate: 'Thu, 12 Nov 2015 21:16:39 +0000'\n      creator: \"John Doe\"\n      content: '\u003ca href=\"http://example.com\"\u003ethis is a link\u003c/a\u003e \u0026amp; \u003cb\u003ethis is bold text\u003c/b\u003e'\n      contentSnippet: 'this is a link \u0026 this is bold text'\n      guid: 'https://www.reddit.com/r/funny/comments/3skxqc/the_water_is_too_deep_so_he_improvises/'\n      categories:\n          - funny\n      isoDate: '2015-11-12T21:16:39.000Z'\n```\n\n##### Notes:\n* The `contentSnippet` field strips out HTML tags and unescapes HTML entities\n* The `dc:` prefix will be removed from all fields\n* Both `dc:date` and `pubDate` will be available in ISO 8601 format as `isoDate`\n* If `author` is specified, but not `dc:creator`, `creator` will be set to `author` ([see article](http://www.lowter.com/blogs/2008/2/9/rss-dccreator-author))\n* Atom's `updated` becomes `lastBuildDate` for consistency\n\n## XML Options\n\n### Custom Fields\nIf your RSS feed contains fields that aren't currently returned, you can access them using the `customFields` option.\n\n```js\nlet parser = new Parser({\n  customFields: {\n    feed: ['otherTitle', 'extendedDescription'],\n    item: ['coAuthor','subtitle'],\n  }\n});\n\nparser.parseURL('https://www.reddit.com/.rss', function(err, feed) {\n  console.log(feed.extendedDescription);\n\n  feed.items.forEach(function(entry) {\n    console.log(entry.coAuthor + ':' + entry.subtitle);\n  })\n})\n```\n\nTo rename fields, you can pass in an array with two items, in the format `[fromField, toField]`:\n\n```js\nlet parser = new Parser({\n  customFields: {\n    item: [\n      ['dc:coAuthor', 'coAuthor'],\n    ]\n  }\n})\n```\n\nTo pass additional flags, provide an object as the third array item. Currently there is one such flag:\n\n* `keepArray (false)` - set to `true` to return *all* values for fields that can have multiple entries.\n* `includeSnippet (false)` - set to `true` to add an additional field, `${toField}Snippet`, with HTML stripped out\n\n```js\nlet parser = new Parser({\n  customFields: {\n    item: [\n      ['media:content', 'media:content', {keepArray: true}],\n    ]\n  }\n})\n```\n\n### Default RSS version\nIf your RSS Feed doesn't contain a `\u003crss\u003e` tag with a `version` attribute,\nyou can pass a `defaultRSS` option for the Parser to use:\n```js\nlet parser = new Parser({\n  defaultRSS: 2.0\n});\n```\n\n\n### xml2js passthrough\n`rss-parser` uses [xml2js](https://github.com/Leonidas-from-XIV/node-xml2js)\nto parse XML. You can pass [these options](https://github.com/Leonidas-from-XIV/node-xml2js#options)\nto `new xml2js.Parser()` by specifying `options.xml2js`:\n\n```js\nlet parser = new Parser({\n  xml2js: {\n    emptyTag: '--EMPTY--',\n  }\n});\n```\n\n## HTTP Options\n\n### Timeout\nYou can set the amount of time (in milliseconds) to wait before the HTTP request times out (default 60 seconds):\n\n```js\nlet parser = new Parser({\n  timeout: 1000,\n});\n```\n\n### Headers\nYou can pass headers to the HTTP request:\n```js\nlet parser = new Parser({\n  headers: {'User-Agent': 'something different'},\n});\n```\n\n### Redirects\nBy default, `parseURL` will follow up to five redirects. You can change this\nwith `options.maxRedirects`.\n\n```js\nlet parser = new Parser({maxRedirects: 100});\n```\n\n### Request passthrough\n`rss-parser` uses [http](https://nodejs.org/docs/latest/api/http.html#http_http_get_url_options_callback)/[https](https://nodejs.org/docs/latest/api/https.html#https_https_get_url_options_callback) module\nto do requests. You can pass [these options](https://nodejs.org/docs/latest/api/https.html#https_https_request_options_callback)\nto `http.get()`/`https.get()` by specifying `options.requestOptions`:\n\ne.g. to allow unauthorized certificate\n```js\nlet parser = new Parser({\n  requestOptions: {\n    rejectUnauthorized: false\n  }\n});\n```\n\n## Contributing\nContributions are welcome! If you are adding a feature or fixing a bug, please be sure to add a [test case](https://github.com/bobby-brennan/rss-parser/tree/master/test/input)\n\n### Running Tests\nThe tests run the RSS parser for several sample RSS feeds in `test/input` and outputs the resulting JSON into `test/output`. If there are any changes to the output files the tests will fail.\n\nTo check if your changes affect the output of any test cases, run\n\n`npm test`\n\nTo update the output files with your changes, run\n\n`WRITE_GOLDEN=true npm test`\n\n### Publishing Releases\n```bash\nnpm run build\ngit commit -a -m \"Build distribution\"\nnpm version minor # or major/patch\nnpm publish\ngit push --follow-tags\n```\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frbren%2Frss-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frbren%2Frss-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frbren%2Frss-parser/lists"}