FreshRSS List Widget for Homepage

A custom widget for gethomepage.dev that displays the latest RSS feed items from your FreshRSS subscriptions.

Why?

The built-in FreshRSS widget for Homepage only shows the unread count. This widget goes a step further by listing the actual articles from your reading list (or a specific category) directly on your dashboard.

Features

• Lists recent RSS items with title, date, author, and source feed.
• Supports filtering by FreshRSS category/label.
• Configurable number of items to display.
• Links directly to the article.

Prerequisites

• A running FreshRSS instance with the Google Reader API enabled.
  • In FreshRSS: Settings → Profile → API management → Enable API and set your API password.
  • Ensure the Google Reader API endpoint (api/greader.php) is accessible.

Installation

1. Copy the freshrsslist folder into your Homepage widgets directory (e.g., src/widgets/ or your custom widgets path).
2. If Homepage requires widget registration, import and add it to your widget registry.

Configuration

Add the widget to your services.yaml (or widgets.yaml):

- FreshRSS:
    href: https://your-freshrss-instance.com
    widget:
      type: freshrsslist
      url: https://your-freshrss-instance.com
      username: your_username
      password: your_api_password  # Not your regular login password
      category: Tech # Optional: filter by FreshRSS label
      limit: 5       # Optional: number of items (default: 5)

Options

Field	Required	Description
url	Yes	Base URL of your FreshRSS instance.
username	Yes	Your FreshRSS username.
password	Yes	Your FreshRSS API password (set in Profile → API management).
category	No	A FreshRSS category/label to filter items. Omit to show reading list.
limit	No	Number of items to display. Default: 5.

How It Works

The widget authenticates with FreshRSS via the Google Reader API (ClientLogin) and fetches the stream contents. It then maps the API response to a clean list of articles rendered inside a Homepage service container.

File Structure

• widget.js — Defines the widget endpoint and proxy handler.
• proxy.js — Handles FreshRSS authentication and API requests.
• components.jsx — The React component that renders the RSS list.

License

MIT