Skip to content

derek-zhou/airss

main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 

Airss

Airss is a light weight RSS feed reader that runs entirely in your browser.

Introduction

Airss is an opinionated feed reader that is designed to aggregate blogs and news in one place for you to read. It provides only the essential functionalities on the surface: You give it a bunch of feeds, it will feed you all the news, one item at a time. The benefits are:

  • No software to install, no service to sign up, no middle man, no cookie, no tracking, completely free with no string attached.
  • It is tiny: <100KB transfer size (the airtable client being the bulk of it) for now, and that's html, style, and scripts all put together. I don't even bother with minifying them.
  • Supports JSON feeds, RSS2 feeds and Atom feeds. Also automatically figures out feed url from typical web pages through rel=alternate links
  • You can optionally use your own airtable to store your feeds so you can hop between several devices.
  • You can optionally use roastidio.us to load feeds to bypass the CORS restriction (more on this later).
  • You can optionally use the roastidio.us commenting service (written and operated by me) to write your comment with a click of the button (🔥). The integration is just a simple link, there is no data sharing.

You need a ES2017 compliant browser (sorry, IE fans). The main branch is auto-deployed here: airss.roastidio.us which is on Vercel. All are welcome to use it. Since the software is open sourced, you can also clone it and host it somewhere else; it is all upto you.

There are only a few buttons, so just try it out. If you close the tab or the browser, don't be afraid: your data is not lost and you can pick up right at where you left off the next time you open it. For the curious minds, the application state is persisted locally via indexed db; nothing goes out to the internet.

To subscribe to a feed, you can click the (🍼) button then paste in a link. The link could be a feed (RSS2, Atom or JSON) link or a web page that the proper rel=alternate links. Airss will figure it out automatically.

You can also use the this bookmarklet:

javascript:location.href='https://airss.roastidio.us/?url='+encodeURIComponent(window.location.href)

to subscribe to any blog. Github does not allow a link with javascript: URL, so you need to bookmark any page, such as this page, then edit the property of your newly created bookmark, give it a name such as subscribe in airss and paste in the above bookmarklet string as it's location. Next time you came across an interesting blog, just click the bookmarklet and you are done.

The above trick might not work in a mobile browser. On Android, you can install the excellent app URL Forworder by David Laurell to forward the link to Airss.

There is another trick: If your blog's index page links to Airss and your visitor click this link, the visitor will automatically subscribe to your blog. This magic happens in two steps: first, Airss uses referrer to figure out where the visitor is comming from, then it uses the rel=alternate links of that page to find out the feed. Neat, huh?

One thing to keep in mind is you have to make sure the referer header is intact. In Firefox 87+ the default of referrer policy is very strict, it will strip off path and query string when crossing origins. So you would need to add the proper referrerpolicy attribute in the link:

<a href="https://airss.roastidio.us/?subscribe-referrer" referrerpolicy="no-referrer-when-downgrade">Follow me with Airss!</a>

Comments or PRs are welcome.

Caveat

The biggest caveat is that through no fault of its own, it only works with very few feeds, unless you do something extra (see later). The reason is CORS. For more info please see: enable CORS. The TL; DR is your browser will prevent Airss from accessing other websites. Airss has to fetch and parse feeds, and:

  • The feeds are usually static, so the cross site accesses pose no risk at all
  • They shall be considered public API entry points anyway

So it is completely safe. If you are a blogger and operate your own web server, please see the the link: enable CORS to find out how to enable CORS and reach out to a broader audience. Among the major hosting platforms out there, Vercel and github pages enable unrestricted CORS by default for all static files, big kudos to them.

Cures for CORS

Hope is not lost, even today. If you use a user script manager such as Greasemonkey, Violentmonkey, or Tampermonkey, you can install this user script. Installing it will immediately make the Airss instance on airss.roastidio.us be able to access all feed URLs, including ones that are cross-origin or http only. (Access for other instances can be added by editing the script.)

CORS restriction can also be turned off by browser add-ons such as: CORS everywhere and CORS changer, on Firefox and Chrome. Please install one of the add-ons, whitelist https://airss.roastidio.us and everything shall be fine. Safafi users can turn on the develop menu and disable the cross-origin restrictions from the menu. Mobile users please see the next section. If you are really paranoided, you are welcome to audit my source code to make sure there is nothing funny going on.

Proxy

I provide a proxy service through Roastidio.us to anyone, without needing to login, so the CORS restriction can be circumvented, no user scripts or browser add-ons are needed. Just check the box Load feeds with roastidio.us (default checked now) in the config page and all should be good; no browser plugin or developer menu is required.

  • Loading feeds should be faster because Roastidio.us will load feeds in the background and cache the results
  • If I turn evil I could sabotage the feed content, but your privacy will not be harmed
  • The feed owners will not know your IP or browser fingerprint so you remain completely anonymous

Roastidio.us is a free commenting service open to everyone, and is written and operated by the me. To actually post a comment you do need to login (free registration).

By the way, I am accumulating high quality feeds to build a search engine specifically design for feeds. Any feed you load via roastidio.us will be indexed. When and who load the feeds are not recorded to respect your privacy. You are welcomed to try the search engine right now: Roastidio.us Search (free registration required)

Airtable

The folks at Airtable are nice enough to provide anyone free accounts. With Airtable you can share feeds and news between multiple devices that you control, such as your computer + your phone etc., so you can read your news anywhere. There is some setup involved because airtables cannot be setup through API. You will need to setup a dedicated base for Airss, and 2 tables under the base. The easiest way is to just copy this blank template: airss template into your workspace.

Then you generate a API key through your account profile, and take a note of the base ID from help -> API documentation in this base. Put them in the config page of Airss, then you are done.

Airtable's free tier can store upto 1200 records in a base. Each feed is a record, and each news item is a record too. If you subscribe to a lot of feeds, you may have to limit history depth to stay in the bound. Alternatively, you can hop onto airtable to delete old items manually.

Please also keep in mind that the two-way data syncing and conflicts resolution of Airss is not very robust and it tries to be consevertive when in doubt. You may see some items double-fetched on some of your devices.

Modes of operation

Depends on whether you use airtable, roastidio.us or not, there can be 4 modes of operation:

  • Use neither. Then Airss remains a pure client-side application with the freedom and technical limitation of a pure client-side application.
  • Use Roastidio.us but not Airtable. Airss would be enhanced with the hack-free, fast background load of feeds.
  • Use Airtable but not Roastidio.us. Feeds and feed items would be synced among all browsers and devices using the same Airtable credential.
  • Use both. In addtion to having the best of both worlds, the usage of Airtable would be greatly reduced. In this mode, only the feeds, not feed items are synced through Airtable, so the 1200 records apply only to feeds you subscribed. That's a lot of feeds!

Disclaimer

The software shall be consider beta quality right now. Use it at your own risk.

Do not use Airss with Airtable on a device that you do not control; Airss stores the API key in the local storage unencrypted. A local super user could steal the credential and sabotage your Airtable.

About

A light weight feed reader that runs in your browser, with no backend

Resources

License

Stars

Watchers

Forks

Packages

No packages published