ReadiumX

https://github.com/user-attachments/assets/1c3a5138-0fc7-43e9-b0a2-761e70f9c83c

ReadiumX

The open-source tool that provides access to premium Medium articles without the paywall



<a href="https://readiumx.com"><strong>Learn more »</strong></a>






<a href="#introduction"><strong>Introduction</strong></a> ·
<a href="#features"><strong>Features</strong></a> ·
<a href="#tech-stack"><strong>Tech Stack</strong></a> ·
<a href="#contributing"><strong>Contributing</strong></a>

Introduction

ReadiumX is an open source tool that provides access to premium Medium articles without the paywall, allowing you to bookmark, and manage your reading experience across any device

Tech Stack

• Next.js – framework
• TypeScript – language
• Tailwind – CSS
• TursoDB – database
• Clerk – auth and auth emails
• DrizzleORM – ORM
• TipTap – editor
• Shadcn – component library
• Cloudflare Workers – deployments and article extraction cache

Features

• Access Premium Articles: Bypass paywalls to access content freely.
• Bookmarking System: Save your favorite articles for later reading.
• Progress Tracking: Automatically saves your reading progress to resume where you left off.
• Reading History Management: View and manage your reading history with options to delete records.

Running Locally

1. Clone the repository

bash git clone https://github.com/JaleelB/readium-x.git

1. Install dependencies using pnpm

bash pnpm install

1. Copy the .env.example to .env.local and update the variables.

bash cp .env.example .env.local

1. Start the normal Next.js development server

bash pnpm run dev

This runs at http://localhost:3156. In this mode, Cloudflare bindings are simulated through OpenNext's local dev bridge when available. If the READIUMX_ARTICLE_CACHE binding is not available, scraping still works; it simply skips the server-side KV cache and uses the existing client session cache.

1. Push the database schema

bash pnpm run db:push

1. To test the app in the Cloudflare Workers runtime locally, copy .dev.vars.example to .dev.vars, fill in the values, then run:

bash cp .dev.vars.example .dev.vars pnpm preview

pnpm preview builds the OpenNext worker and starts Wrangler, usually at http://localhost:8787. This is the mode to use when you specifically want to verify the Cloudflare KV cache behavior before deployment.

Cloudflare Deployment

ReadiumX deploys to Cloudflare Workers through OpenNext.

1. Create separate remote KV namespaces for production and preview:

bash pnpm wrangler kv namespace create readiumx-article-cache pnpm wrangler kv namespace create readiumx-article-cache-preview

These commands create the real Cloudflare KV namespaces. They require wrangler login locally or CLOUDFLARE_API_TOKEN in CI. For day-to-day pnpm dev, you do not need to run them first; they are required before deploying or testing against real Cloudflare resources.

1. Put the generated namespace IDs into wrangler.jsonc for the READIUMX_ARTICLE_CACHE binding. Keep the production namespace as id and the preview namespace as preview_id. If Wrangler offers to add the binding for you, use READIUMX_ARTICLE_CACHE as the binding name; the app does not read lowercase binding names.

2. Add the application variables and secrets from .dev.vars.example to Cloudflare Workers.

3. Add these GitHub repository secrets for deployment:

4. CLOUDFLARE_ACCOUNT_ID

5. CLOUDFLARE_API_TOKEN

6. Preview or deploy:

bash pnpm preview pnpm deploy

Setting up Google Provider

If you want google login, you'll need to setup a google project and create some keys:

1. https://console.cloud.google.com/apis/credentials
2. create a new project
3. setup oauth consent screen
4. create credentials - oauth client id

5. for authorized javascript origins

6. http://localhost:3000

7. https://your-domain.com

8. Authorized redirect URIs

9. http://localhost:3000/api/login/google/callback

10. https://your-domain.com/api/login/google/callback

11. Set your google id and secret inside of .env

12. GOOGLE_CLIENT_ID

13. GOOGLE_CLIENT_SECRET

Setting up Github Provider

If you want github login, you'll need to setup a github project and create some keys:

1. https://github.com/settings/developers
2. Create a new OAuth App
3. Create an application for the for local development:
4. Homepage URL: http://localhost:3000
5. Authorization callback URL: http://localhost:3000/api/login/github/callback
6. Create an application for the for production:
7. Homepage URL: https://your-domain.com
8. Authorization callback URL: https://your-domain.com/api/login/github/callback

Contributing

Contributions are welcome! Please open an issue if you have any questions or suggestions. Your contributions will be acknowledged. See the contributing guide for more information.

License

Licensed under the MIT License. Check the LICENSE file for details.