Create a custom route and use it with the Docker image

[bdovaz]

I see that this process isn't documented. Is there a way to do it?

In my case, there's a specific page I want to create a route for by scraping the HTML, and it doesn't make sense to create a PR because it's a very specific page in my town.

Thanks.

[dosubot[bot]]

Hi @bdovaz! I'm Dosu and I’m helping the RSSHub team.

You're right that this isn't well documented. Unfortunately, the official Docker image doesn't support mounting custom routes at runtime — routes are compiled into a static bundle at build time [1], so volume mounting doesn't work.

Here are your two main options:

Option 1: Build a custom Docker image (recommended)

1. Clone/fork RSSHub

2. Add your route to lib/routes/{namespace}/ (e.g., lib/routes/mytown/)

3. Build your own image:

   docker build -t my-rsshub .

4. Run it:

   docker run -d -p 1200:1200 my-rsshub

You'll need to rebuild whenever you want to update RSSHub upstream, but for a personal scraping route this is the most straightforward approach.

Option 2: Use RSSHub as an npm package

RSSHub exposes a registerRoute() API (cite:code_file:218b556b:40-75) that lets you programmatically add routes at runtime:

import { init, registerRoute } from 'rsshub';

await init();

registerRoute('mytown', {
    path: '/events',
    name: 'My Town Events',
    handler: async (ctx) => ({
        title: 'Town Events',
        link: 'https://mytown.example.com',
        item: [/* your scraped items */],
    }),
});

This still requires building your own Docker image to run it, but keeps your code separate from the RSSHub source.

---

For your HTML scraping use case, you'd use cheerio (already included in RSSHub) in your route handler. The route development guide covers the structure and data retrieval methods including HTML parsing.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[bdovaz]

@dosu how can I deploy my own Docker image using Option 2 There are no examples; the repository only uses the pkg.ts API in the tests.

[dosubot[bot]]

You're right — the pkg API is limited in this regard. After investigating the code, the rsshub package exports init(), registerRoute(), and request() [1], but it does not expose the Hono app instance or provide a way to start an HTTP server. The app is kept as a private module variable internally [2] and is not part of the library's published exports [3].

So Option 2 (using RSSHub as an npm package) only supports programmatic data fetching, not serving an HTTP server:

import { init, registerRoute, request } from 'rsshub';

await init();
await registerRoute('mytown', {
    path: '/events',
    name: 'Town Events',
    handler: async (ctx) => ({
        title: 'Town Events',
        link: 'https://mytown.example.com',
        item: [/* scraped items */],
    }),
});

// Fetch RSS data programmatically (no HTTP server)
const data = await request('/mytown/events');

This is useful for batch jobs or integrations, but not for serving feeds over HTTP.

---

For your use case (serving a custom route via Docker), Option 1 is the practical path:

1. Clone the RSSHub repo
2. Add your route to lib/routes/mytown/ (following the route authoring guide)
3. Build and run with Docker:

   docker build -t my-rsshub .
   docker run -d -p 1200:1200 my-rsshub

Your feed would then be available at http://localhost:1200/mytown/your-path.

This is the only way to get custom routes served over HTTP with Docker today, since the pkg API doesn't expose server functionality.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[bdovaz]

@dosu Is it possible to create a wrapper server (http.createServer) and call that method?

[dosubot[bot]]

Yes, this is possible! The trick is that internally, app.request(path) returns a full HTTP Response object containing RSS XML before the request() wrapper parses it as JSON [1]. The template middleware handles all the Data→XML conversion [2].

You can create a wrapper server like this:

import { init, registerRoute } from 'rsshub';
import { createServer } from 'node:http';

await init();

// Register your custom route
await registerRoute('mytown', {
    path: '/events',
    name: 'Town Events',
    handler: async (ctx) => ({
        title: 'Town Events',
        link: 'https://mytown.example.com',
        item: [/* your scraped items */],
    }),
});

// The undocumented part: access the internal app via the request() internals
// Since app isn't exported, you'd need to use request() and work with the JSON,
// OR you can import the app from the package's internals if available in the build.

However, there's a catch: the Hono app instance is stored as a private variable and is not exported from the package [3]. The public request() function forces .json() parsing on the response [4], giving you a Data object rather than the rendered XML.

Practical workaround: You could still build a wrapper server using the JSON Data output and a feed library like feed to re-serialize it:

import { init, registerRoute, request } from 'rsshub';
import { createServer } from 'node:http';
import { Feed } from 'feed';

await init();
await registerRoute('mytown', { /* ... */ });

const server = createServer(async (req, res) => {
    const data = await request(req.url); // returns parsed Data object
    // Convert Data to RSS XML using a library like 'feed'
    const feed = new Feed({ title: data.title, link: data.link, id: data.link });
    for (const item of data.item || []) {
        feed.addItem({ title: item.title, link: item.link, description: item.description });
    }
    res.writeHead(200, { 'Content-Type': 'application/xml' });
    res.end(feed.rss2());
});

server.listen(1200);

That said, this adds an unnecessary serialization round-trip. For your use case, Option 1 (building a custom Docker image with your route in lib/routes/) is significantly simpler — you get the full RSSHub server with all its middleware, caching, and XML rendering out of the box, and you just need to add your route file and rebuild.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.