Skip to content

README.EN.md

Latest commit

Β 

History

History
395 lines (273 loc) Β· 23.1 KB

README.EN.md

File metadata and controls

395 lines (273 loc) Β· 23.1 KB
Raw

RSSBook

RSSBook Favicon
Your Feed Generator, Toolkits and Blogger.
README CN EN
HELPER OpenAPI Utils Feed Helper(WIP)
ARTICLES Contributing How to Create a Feed(CN/EN)
  • RSSBook is a Feed generator, serving as a lightweight alternative to RSSHub.
  • RSSBook is a Feed toolkit for quickly merging/filtering/transforming feeds, and even generating feeds from web pages without code.
  • RSSBook is a Feed blog that lets you create your own space by subscribing to feeds from various platforms (e.g., GitHub, Weibo, Bilibili).

Caution

Before version 1.0, this project is not yet stable. We haven't implemented features like an online generator, Puppeteer integration, AI support, automatic upstream sync, and better library support yet. We still have a long way to go, and your help in improving the project is welcome.

Project Structure

This project uses a Monorepo structure managed with Bun Workspaces:

RSSBook/
β”œβ”€β”€ pkgs/
β”‚   β”œβ”€β”€ rssbook/              ← Core package (Feed parsing, routes, plugins, themes, etc.)
β”‚   └── utils-feed-helper/    ← Helper package (Feed utility tools)
β”œβ”€β”€ platform/
β”‚   β”œβ”€β”€ cloudflare/           ← Cloudflare Workers entry
β”‚   β”œβ”€β”€ deno/                 ← Deno entry
β”‚   β”œβ”€β”€ node/                 ← Node.js entry
β”‚   └── vercel/               ← Vercel entry
β”œβ”€β”€ scripts/                  ← Script tools
└── docs/                     ← Documentation

All platform entries are based on pkgs/rssbook/src/RSSBookApp.ts. Community contributions for more runtime/provider support are welcome.

Getting Started

This guide will help you quickly set up and configure RSSBook. For a tutorial on writing new routes, see CONTRIBUTING.md.

Setting Up the Environment

RSSBook can run in multiple environments, but we use Bun for development and testing. If you're deploying RSSBook in production, we recommend using Bun.

If you haven't installed a JavaScript runtime yet, please install Bun first. See Bun Installation for instructions.

Then, you need to install Git to clone the repository. See Git Installation for instructions.

Finally, install a code editor that supports TypeScript, such as Visual Studio Code, JetBrains IDEs, or the newer Zed.

Open a terminal in your desired location and run the following commands to clone the repository and install dependencies:

# Clone the repository
git clone https://github.com/HackHTU/RSSBook.git
# Enter the directory
cd RSSBook
# Install dependencies
bun install

Open the RSSBook folder in your code editor, and you're ready to start configuring and developing.

Development and Deployment

We develop and test using Bun. Bun is an all-in-one runtime/package manager/tester/bundler with excellent performance and low resource usage. If you're deploying RSSBook in production, we recommend using Bun.

Of course, we also support other runtimes/providers. Some of these providers have predefined environments (e.g., KV and databases), so we provide platform-specific entry packages in the platform directory for you to choose from.

Tip

We have a public instance list at HOSTS. When accessing the OpenAPI documentation, available instances may be displayed. If you'd like to share your instance with everyone, feel free to submit a Pull Request with your URL/version info/other notes. We appreciate your contribution!

Platform-Specific Notes

Tip

Before diving into the platform-specific notes below, please read the Initial Configuration section first to learn how to configure RSSBook via the RSSBookApp function and Environment Variables.

Bun

The entry file for Bun is in the rssbook core package: pkgs/rssbook/src/index.ts.

Bun is a... I won't say more, it's just really fast. For production, you can build a binary for optimal performance:

# All supported targets: https://bun.com/docs/bundler/executables#supported-targets
bun build --define NODE_ENV='"production"' --compile --minify-whitespace --minify-syntax --target bun-linux-x64 --outfile server pkgs/rssbook/src/index.ts
Node.js

The entry file for Node.js is in the platform-node package: platform/node/index.ts.

Node.js is the most mainstream JavaScript runtime. For development, since Node.js's native TypeScript support is not yet complete, we recommend using tsx to start the server (configured in the package's dev script).

Deno

The entry file for Deno is in the platform-deno package: platform/deno/index.ts.

Deno is another runtime following Node.js.

Deploy on Deno

If you prefer to configure the build settings manually in the Deno Dashboard, you can refer to the following parameters:

  • App Directory: platform/deno
  • Install command: (leave empty)
  • Build command: (leave empty)
  • Pre-deploy command: (leave empty)

After deployment, you also need to enable Deno KV persistent storage in the Deno Deploy console at https://console.deno.com/{user}/{project}/databases, which is used as the default cache backend for RSSBook.

CloudFlare Workers

I personally love CloudFlare Workers. It's a serverless computing platform based on the V8 engine that generously provides a free tier, making it perfect for deploying RSSBook.

The entry file for CloudFlare Workers is in the platform-cloudflare package: platform/cloudflare/index.ts.

For production, you can directly click the button below to deploy to CloudFlare Workers. After deployment, you can customize RSSBook configuration through environment variables or a wrangler config file in the Cloudflare Workers settings (see the Initial Configuration - Environment Variables section).

Deploy to Cloudflare

A better approach is to fork this repository, modify the configuration in Github CodeSpace or locally, then configure your own GitHub repository in Cloudflare Workers settings for deployment (or you can use GitHub Workflow).

If you prefer to configure the build settings manually in the Cloudflare Dashboard, you can refer to the following parameters:

  • Build command: bun run build
  • Deploy command: cd platform/cloudflare && bunx wrangler deploy
  • Versions command: cd platform/cloudflare && bunx wrangler versions upload
  • Root directory: (leave empty)
Vercel

Vercel is a popular serverless computing platform that also provides a generous free tier.

The entry file for Vercel is in the platform-vercel package: platform/vercel/api/index.ts.

Vercel deployment settings are defined in platform/vercel/vercel.json, which sets the Framework Preset to Other.

Deploy with Vercel

Initial Configuration

After finding the corresponding entry file (each platform's entry file is in its own package), you can start configuring RSSBook.

In the entry file, you should see a createRSSBookApp function used to create the RSSBook application instance. You can modify it according to your needs.

/* ... */
createRSSBookApp({
    // Configuration options here
})
/* ... */

Tip

For some entry files, we have default configurations. For example, in platform/cloudflare/index.ts, we use CloudFlare Workers KV as the default caching solution, which you can modify as needed.

Configuration Reference

The createRSSBookApp function in each platform's entry file accepts a configuration object. This guide helps you understand common configuration options across feature modules.

Environment Variables

You can also configure RSSBook via environment variables. All available variables defined in pkgs/rssbook/src/app.ts are listed below.

Name Type Description Default Example
RSSBOOK_BOOK_CACHE_MAX_AGE_MS Number (ms) Cache TTL in milliseconds for aggregated book feed data. 600000 (10 minutes) RSSBOOK_BOOK_CACHE_MAX_AGE_MS="600000"
RSSBOOK_BOOK_CONFIG key=value list Feed source config values, as comma-separated key=value pairs. {} RSSBOOK_BOOK_CONFIG="GITHUB_TOKEN=token,DISCORD_TOKEN=token"
RSSBOOK_BOOK_FEEDS URL list Feed URLs aggregated by the book page, as a comma-separated string. https://rssbook.htu.me/feeds/programming/github/trending/daily RSSBOOK_BOOK_FEEDS="https://rssbook.htu.me/feeds/programming/github/trending/daily"
RSSBOOK_BOOK_THEME Theme name Built-in book theme. Allowed values: gallery magazine masonry minimal reader redbook. redbook RSSBOOK_BOOK_THEME="redbook"
RSSBOOK_META_DESCRIPTION String Page description rendered in HTML metadata. not rendered RSSBOOK_META_DESCRIPTION="A simple RSS feed aggregator and reader."
RSSBOOK_META_KEYWORDS String list Page keywords rendered in HTML metadata, as a comma-separated string. not rendered RSSBOOK_META_KEYWORDS="rss,reader,feeds"
RSSBOOK_META_LANG String HTML language value. not rendered RSSBOOK_META_LANG="en"
RSSBOOK_META_TITLE String Page title rendered in HTML metadata. not rendered RSSBOOK_META_TITLE="RSSBook"
RSSBOOK_OPENAPI_ENABLE_FETCH_ONLINE_SERVER Boolean Enable fetching public online server entries for the OpenAPI server list. true RSSBOOK_OPENAPI_ENABLE_FETCH_ONLINE_SERVER="true"
RSSBOOK_STATIC Boolean Enable static asset serving. true RSSBOOK_STATIC="false"

Note

Array-shaped values (e.g. RSSBOOK_BOOK_FEEDS, RSSBOOK_META_KEYWORDS) are provided as comma-separated strings. Source config values use comma-separated key=value pairs. Booleans accept true false 1 0 yes no on off (case-insensitive); any other value is ignored.

Using the Personal Homepage

Typically, your blog and social platform activities (like YouTube, Reddit, and Mastodon) provide Feed links. For platforms without Feed support, you can generate Feed links through this project.

But have you ever thought about integrating feeds from various platforms to create your own personal homepage? You can achieve this by integrating your activities from different social platforms.

In the configuration file, you can configure the feeds you want to integrate using feeds.

Viewing the Route List

After starting the development server or deploying, you can access the /openapi path to view the list of routes supported by the current instance. The sidebar displays routes by category, and you can use search (Meta + K) to find the route you want.

The general route path is GET /feeds/{{category}}/{{route}}. You can check the route list to find the corresponding path, then click the Test Request button to test the route. Each route also shows its parameter list, maintainer information, configuration options, and other basic information.

Since different RSSBook versions may have different routes and features, please refer to the documentation at the beginning of your instance's OpenAPI for more information.

By default, the output Feed format is RSS 2.0. You can adjust the output format by adding the type query parameter. When the query parameter is ?type=html, the theme will render the Feed as a website.

There's also a boolean query parameter styled to control whether to enable the XSL stylesheet for styling the Feed display. In browsers that support XML XSL stylesheets, the displayed Feed will have better readability.

Using Utility Routes

We provide convenient Feed routes such as merge, sort, filter, and fetch, which can be very useful for people who don't know how to write code.

In the OpenAPI documentation, you can find and generate them under the utils category.

Creating Routes

For how to write new routes, route specifications, and writing tests, see How to Create a Feed.

Tip

If you use an AI coding assistant (Cursor, Claude Code, Codex, opencode, etc.) to generate or modify feed routes, ask it to read this repo's create-feed skill first. The skill describes the Source code structure, registration location, naming conventions, available utilities (cache date ofetch load formatHTML parse toAbsoluteURL, etc.), and testing guidelines, so the AI can produce code that follows the project conventions in one pass and avoid introducing new dependencies or reinventing the wheel.

Advanced Tutorial

To facilitate customization, we尽量 avoid complex tech stacks. Our backend uses the ElysiaJS framework.

On the frontend, we use Kita/html as a blazing-fast JSX runtime for SSR. For the default theme, we only use UnoCSS (similar to TailwindCSS) and DataStar (a declarative framework similar to HTMX + Alpine.js) runtimes imported via CDN without a build process (JavaScript imported directly in HTML), which works very well.

Customizing the Default Theme

In pkgs/rssbook/src/books/theme, you can find the default theme code. You only need some JSX syntax knowledge and CSS/Tailwind syntax to modify it according to your needs.

You can also integrate DataStar/Htmx/Alpinejs and other popular micro-frameworks into the default theme. See Kita/html Integrations and try writing JavaScript code to customize theme functionality.

Tip

Fun fact: the default theme was created using Vibe Coding.

Thanks to TSX's type safety, AI can easily write themes. You can also use your preferred AI with Context7 MCP for better understanding of the above frameworks. We also welcome you to open-source your themes.

When previewing RSS/Atom XML in the browser, we use XSLT for simple styling. This is an older version and may be removed in the future, so it's only for basic preview functionality. You can find the corresponding files in pkgs/rssbook/src/public/xsl and modify them as needed.

Writing New Themes

When writing new themes, you can refer to the theme type definitions or the default theme implementation.

In pkgs/rssbook/src/types/theme.ts, you can find the theme type definitions and write new themes according to your needs.

Tip

You can create a theme factory function (props) => Theme to generate theme instances, making themes more configurable. Then you can publish it as an npm package for others to use.

Use Cases

RSSBook can be used not only as your Feed reader but also for many other purposes. Here are some common use cases.

Creating Your Personal Activity Feed

RSSBook's Book feature aggregates any number of feeds and renders them as a personal homepage through a theme template, making it perfect as your "digital living room."

Typical steps:

  1. Configure the feeds you want to aggregate via the RSSBOOK_BOOK_FEEDS environment variable (or by calling RSSBookApp({ book: { feeds: [...] } }) in your entry file). For example: 
    RSSBOOK_BOOK_FEEDS="https://your-instance/feeds/programming/github/events/vercel,https://your-instance/feeds/programming/github/trending/daily,https://your-instance/feeds/multimedia/sspai/matrix"
  2. (Optional) Pick a built-in theme with RSSBOOK_BOOK_THEME: 
    RSSBOOK_BOOK_THEME="redbook"
    Allowed values: gallery magazine masonry minimal reader redbook.
  3. (Optional) Customize page metadata via RSSBOOK_META_TITLE / RSSBOOK_META_DESCRIPTION / RSSBOOK_META_LANG / RSSBOOK_META_KEYWORDS: 
    RSSBOOK_META_TITLE="My Personal Feed"
RSSBOOK_META_DESCRIPTION="My personal activity aggregator"
RSSBOOK_META_LANG="en"
RSSBOOK_META_KEYWORDS="rss,reader,personal"
  4. After deployment, visit your instance's homepage to see the aggregated page. You can also force HTML rendering with ?type=html and enable the XSL stylesheet with styled=true.

If some feed sources require authentication (e.g., a GitHub Token), inject them into RSSBOOK_BOOK_CONFIG as key=value pairs:

RSSBOOK_BOOK_CONFIG="GITHUB_TOKEN=ghp_xxx"

Each feed source reads the config keys it declares (see GITHUB_TOKEN usage in pkgs/rssbook/src/routers/feeds/programming/github/index.ts).

Syncing to IM Platforms Using Automation Tools

RSSBook itself only "produces feeds," but since the output is standard RSS 2.0, you can plug it into any automation tool that supports RSS subscriptions β€” the most common one is IFTTT.

As an example, let's sync GitHub Trending to a Discord channel:

  1. Get your feed URL. RSSBook ships with a GitHub Trending Daily Feed by default: 
    https://your-instance/feeds/programming/github/trending/daily
    Append ?type=rss to explicitly request the RSS 2.0 format.
  2. Create an Applet on IFTTT: go to Create β†’ If This β†’ choose RSS Feed β†’ select the New feed item trigger β†’ paste the URL above into Feed URL.
  3. Configure the IM action (Then That). Pick one of the following:
    • Discord: choose Discord β†’ Post message to channel β†’ pick the target server and channel β†’ in Message, use IFTTT placeholders, e.g.: 
      πŸ“° {{EntryTitle}}
{{EntryURL}}
      You can also prepend {{FeedTitle}} to tag the source.
    • Telegram: choose Telegram β†’ Send message β†’ connect your bot β†’ in Message text, use {{EntryTitle}} / {{EntryURL}} / {{EntryContent}}.
    • Slack: choose Slack β†’ Post to channel β†’ in Message: 
      *{{EntryTitle}}* β€” {{EntryURL}}
    • Webhooks / WeCom / Feishu bot: choose Webhooks β†’ Make a web request, paste the IM bot's webhook URL into URL, handcraft the JSON body in Body (you can use {{EntryTitle}} and friends), set Method to POST and Content Type to application/json.
  4. Finish and enable. IFTTT will poll the RSS source on its update cadence (typically every 15–30 minutes) and push new entries to your IM platform.

Tip

  • You can create one Applet per RSSBook route, so "GitHub β†’ Discord", "V2EX β†’ Telegram", "Sspai β†’ Slack" stay independent.
  • If your IM platform has no official IFTTT service (e.g., Feishu, DingTalk), prefer the Webhooks action β€” IFTTT will substitute {{EntryTitle}} / {{EntryURL}} / {{EntryContent}} / {{EntryPublished}} / {{FeedTitle}} into your custom request body.
  • To avoid duplicate pushes, enable Filter code (JavaScript) in the Applet settings and gate the trigger on EntryPublished being within the last N hours.

Standards

For sustainable development, we have some code and documentation standards. Here are some common standards.

Route Standards

For how to write new routes, route specifications, and writing tests, see CONTRIBUTING.md.

Other Standards

Type Safety: We recommend using TypeScript's as, any, @ts-ignore keywords as little as possible, as they reduce code maintainability.

Code Formatting: We use Biome as the formatter. We recommend running bun check before committing code to check formatting. We also recommend using JSDOC syntax for comments to improve code readability and maintainability.

Text Formatting: For documentation formatting, we recommend using GitHub Markdown standard syntax. The tone doesn't need to be overly formal, but pay special attention to punctuation usage (full-width vs. half-width) and spacing between Chinese and English text.

Community

We recommend discussing and providing feedback on Github. You can participate in the project by submitting Issues, Pull Requests, or discussing in Discussions.

We recommend communicating only in EN/CN languages, and please use the corresponding language category tags when posting.

For bug reports and feature requests, see ISSUE.

For feature discussions, please use DISCUSSION.

Acknowledgments

This project would not be possible without the support and help of all contributors who have written routes. Thank you for your contributions to the RSSBook project!

Github Contributors

This project's inspiration comes from RSSHub and RSSWorker. This project's development relies on Bun, Cheerio, dayjs, ElysiaJS, Kita/html, ofetch, sanitize-html, unstorage and other excellent open-source projects.

This project is licensed under the MIT License. See the LICENSE file for details.