📰 Private Article Reader

Paste any article link and get a clean reading view — no clutter, no distractions.

Your own Reader Mode, accessible from any device through a link you control.

Works on most public news articles and blog posts. Some websites use anti-bot protection, require JavaScript, a login, or a subscription, and may not be readable.

---

Features:

• Choose between Light, Dark, and Sepia themes.
• Adjust the font size and reading width.
• Your last 100 articles are saved locally in your browser.
• Share links that reopen the article in the reader.

---

Getting it running

Choose one:

• Browser — No coding required (recommended) Deploy it from GitHub to Vercel in about five minutes.
• Local — Run it on your computer Best if you want to change the code first.

---

Option A — Browser only

You only need a GitHub account and a free Vercel account.

Step 1 — Make your own copy of the project

Click Fork. This creates your own copy of the project in your GitHub account. Nothing changes in the original project.

Step 2 — Import into Vercel

1. Go to vercel.com/new and sign in.
2. Click Import next to the forked repo.
3. Leave all the build settings as-is — Vercel automatically detects your framework. If it doesn't, select Next.js as the framework preset.
4. (Optional) Add any environment variables now, or skip and add them later under Project → Settings → Environment Variables. See the Settings table below.
5. Click Deploy and wait for the build to finish.

Vercel will give you a public URL (e.g. your-reader.vercel.app). Open it, paste an article URL, and you're reading.

---

Option B — Run it locally

You'll need Node.js installed.

Step 1 — Get the code

git clone https://github.com/braboobssiere/article-reader.git
cd article-reader
npm install

Step 2 — Set up your config file

cp .env.example .env.local

Open .env.local in any text editor. Most settings are optional — see the Settings table below.

Step 3 — Start it up

npm run dev

Open http://localhost:3000 in your browser. Paste an article URL and hit read.

Step 4 — Deploy when ready (optional)

npx vercel

Follow the prompts. Vercel will give you a public URL.

---

Optional: Protect the reader from bots with Turnstile

If you deploy this app publicly, bots and automated scrapers may repeatedly hit the /article endpoint. This wastes bandwidth, increases your Vercel costs, and can get your server IP rate‑limited by news sites.

Cloudflare Turnstile adds a simple, privacy‑preserving CAPTCHA to the submission form. Legitimate human users solve it effortlessly (no puzzles or images – just a single click), while automated requests are blocked before they reach the article fetcher.

How to set it up:

1. Go to dash.cloudflare.com → Turnstile.
2. Click Add a site and give it a name (e.g. article-reader).
3. Add your domain(s) to the Domain field (e.g. vercel.app, or localhost for local testing).
4. Copy the Site Key and Secret Key.
5. Choose security level and pre‑cache options.
6. Add these values to your environment variables:
   • TURNSTILE_SITE_KEY=your-site-key (Plain text)
   • TURNSTILE_SECRET_KEY=your-secret-key (🔒 Secret)
   • TURNSTILE_ENABLED=true (Plain text)

That's it. The CAPTCHA will appear on the home page. Users only need to verify once per session.

---

Optional: Speed up repeat visits with caching

By default the app downloads the article every time it's opened.

Enabling Cloudflare KV stores a copy for a while, making repeat visits much faster and reducing bandwidth.

How to set it up:

1. Go to dash.cloudflare.com → Workers & Pages → KV.
2. Create a new namespace — call it anything, e.g. article-cache. Copy the Namespace ID.
3. Go to My Profile → API Tokens → create a token with Workers KV Storage → Modify permission. Copy the token.
4. Copy your Account ID from the Workers & Pages overview page.
5. Add these values to your environment variables:
   • CLOUDFLARE_ACCOUNT_ID=your-account-id (Plain text)
   • CLOUDFLARE_KV_NAMESPACE_ID=your-namespace-id (Plain text)
   • CLOUDFLARE_API_TOKEN=your-api-token (🔒 Secret)
   • CLOUDFLARE_KV_ENABLED=true (Plain text)
   • (Optional) Set CLOUDFLARE_KV_TTL to control how long articles are cached, in seconds.

Tip: LIVE checkbox will bypasses the cache and fetches the latest version of the article.

---

Settings (environment variables)

Browser-only users: add these in Vercel → Project → Settings → Environment Variables.

Local users: add these to your .env.local file, or in Vercel once deployed.

Most of these are optional. The app works fine without them.

Setting	What it does	Type	Do I need it?
TURNSTILE_ENABLED	Adds a CAPTCHA to stop bots from abusing your reader	Plain text	Only if it's public-facing and you're worried about abuse
TURNSTILE_SITE_KEY	Public key for Cloudflare Turnstile	Plain text	Only if you enabled Turnstile
TURNSTILE_SECRET_KEY	Secret key for the CAPTCHA	🔒 Secret	Only if you enabled Turnstile
CLOUDFLARE_KV_ENABLED	Saves fetched articles in the cloud so repeat loads are instant	Plain text	Nice to have, not required
CLOUDFLARE_ACCOUNT_ID	Your Cloudflare account ID	Plain text	Only if you enabled KV
CLOUDFLARE_KV_NAMESPACE_ID	The ID of your article cache storage bucket	Plain text	Only if you enabled KV
CLOUDFLARE_API_TOKEN	Token that lets the app write to the cache	🔒 Secret	Only if you enabled KV
CLOUDFLARE_KV_TTL	How long (in seconds) to keep an article in the cache. Default is 604800 (7 day) and minimum is 3600 (1 hour).	Plain text	Only if you enabled KV

Tip: If you just want to try the app, leave all of these blank. It will still work — articles just won't be cached between restarts.

---

Privacy & safety notes

• The app only fetches public URLs — it cannot access anything that requires a login.
• Images are loaded directly in your browser when viewing an article. This means the original source website may see your IP address and browser fingerprint. The server does not proxy images; they are loaded client‑side to preserve bandwidth and performance.
• It blocks attempts to fetch internal network addresses (like localhost or private IP ranges), so it's safe to host for others.
• Extracted article content is sanitised to remove anything that could run malicious code.
• Security headers are set automatically.

---

Tech used

Tech	What it is
Next.js	The web framework that runs everything
defuddle	Article extraction
sanitize-html	Removes any dangerous code from extracted content
linkedom	Lightweight DOM parser for server‑side extraction
Eta	Lightweight templating engine for rendering HTML pages
ssrf-guard	Blocks requests to internal/private addresses
Cloudflare KV	Optional cloud storage for caching articles
Brotli	Compresses cached article data
Tailwind CSS	Handles the styling