- TypeScript 56%
- Svelte 40%
- CSS 2%
- HTML 2%
- JavaScript <1%
Mathom #
A reading-first Progressive Web App client for Wallabag, the self-hosted read-later service. Point it at your own Wallabag instance, configure once, and get a reading experience on par with Matter or Readwise Reader — offline-capable, fully customizable, no account required on our end.
Highlights: OAuth2 against your Wallabag, offline reading + offline mutations with replay-on-reconnect, full reader customization (font, size, line height, width, theme), filter by unread/starred/archived/tag, server-side search, add articles by URL paste or Android share sheet, pull-to-refresh on mobile, install-as-app on Android & desktop.
See CLAUDE.md for the full product and technical specification.
Architecture #
[ Your Browser ]
│
│ HTTPS — static assets + service worker
▼
[ Cloudflare Pages: SvelteKit PWA ]
│
│ HTTPS — JSON API calls
▼
[ Cloudflare Worker: mathom-cors (CORS proxy) ]
│
│ HTTPS
▼
[ Your Wallabag instance ]
The PWA is fully static (no SSR). The Worker is a ~50-line CORS shim — it adds the headers Wallabag's API is missing and forwards everything else unchanged. Your Wallabag instance is the source of truth for all data and auth.
Prerequisites #
| Tool | Version | Install |
|---|---|---|
| Bun | 1.x (latest stable) | curl -fsSL https://bun.sh/install | bash |
| Wrangler | (via bunx, no install needed) | bunx wrangler --version to verify |
| Git | any recent | — |
| Cloudflare account | free tier | dash.cloudflare.com |
| Wallabag instance | 2.x | wallabag.org install docs |
You do not need Node.js to work on the PWA. Wrangler (the Cloudflare Worker CLI) is Node-first but runs via bunx in most cases. If you hit a Wrangler issue, install Node 20.x as a fallback for Worker commands only.
Quick start (local development) #
1. Clone #
git clone https://github.com/YOUR_ORG/mathom.git
cd mathom
2. Install dependencies #
cd pwa && bun install
cd ../worker && bun install
3. Configure environment #
# PWA
cp pwa/.env.example pwa/.env.local
# Edit pwa/.env.local — uncomment PUBLIC_DEFAULT_WORKER_URL=http://localhost:8787
# This pre-fills the Worker URL during onboarding so you don't have to type it
# every time. The variable is optional; if unset the production Worker is used.
# Worker has no secrets; wrangler.toml is the config
4. Run the CORS Worker locally #
cd worker
bunx wrangler dev
Wrangler starts a local Worker at http://localhost:8787. Keep this terminal open — the PWA routes all Wallabag API calls through it during development.
Heads up:
bunx wranglerworks for most operations. If you hit a Wrangler-specific crash or hang (file watching issues are the most common), fall back tonpx wrangler devwith a local Node 20.x install.
5. Run the PWA #
In a second terminal:
cd pwa
bun run dev
Vite starts the dev server at http://localhost:5173 with hot module replacement. Changes to .svelte and .ts files reload instantly; service worker changes require a manual browser reload (see Debugging the service worker).
6. First-time setup #
- Open
http://localhost:5173in your browser. - You'll be redirected to
/onboarding. - Enter your Wallabag credentials:
- Wallabag URL — e.g.,
https://wallabag.example.com - Client ID / Client Secret — from your Wallabag API client (see Wallabag configuration)
- Username / Password — your Wallabag login (used once for token exchange, then discarded)
- Worker URL —
http://localhost:8787for local dev
- Wallabag URL — e.g.,
- Click Connect. The app exchanges your credentials for OAuth tokens, then begins syncing articles.
7. Verify sync #
After a few seconds you should see your unread articles at http://localhost:5173/. If you see a CORS error or empty list, check Troubleshooting.
Wallabag configuration #
Create an API client #
- Log in to your Wallabag instance.
- Go to
/developer(e.g.,https://wallabag.example.com/developer). - Click Create a new client.
- Give it a name (e.g., "Mathom") and leave redirect URI blank.
- Copy the Client ID and Client Secret — you'll need these in Mathom's settings.
Recommended server settings #
In your Wallabag server config (parameters.yml or the admin UI):
download_images_enabled: true— Wallabag re-hosts article images on your server. Strongly recommended: avoids opaque cross-origin image responses that balloon your service worker cache and may not cache at all.
Wallabag CORS notes #
Wallabag's CORS support is unreliable. The OAuth endpoint (/oauth/v2/token) in particular does not return CORS headers on error responses, which causes the browser to see a network error instead of a 401. This is the primary reason the CORS Worker exists. See the Wallabag issue tracker for upstream status.
Architecture #
Components #
| Component | Responsibility |
|---|---|
SvelteKit PWA (pwa/) |
UI, local IndexedDB (via Dexie), sync engine, offline queue, service worker |
CORS Worker (worker/) |
Adds CORS headers to Wallabag API responses; validates target URLs; rate-limits |
| Wallabag | Article storage, tagging, auth (OAuth2 password grant) |
Data flows #
Initial auth:
- User enters credentials in
/onboarding. - PWA POSTs to Worker → Worker proxies to
{wallabag_url}/oauth/v2/token. - Tokens stored in IndexedDB settings row. Username/password discarded immediately.
Article sync:
- On app open: GET
/api/entries?since={last_sync_at}(paginated), upsert into Dexie. - Once daily: full ID reconciliation to catch server-side deletes.
last_sync_atupdated on success.
Offline mutations (archive, star, delete):
- User action writes to Dexie immediately (optimistic UI).
- A
PendingMutationis enqueued. - A drainer loop flushes the queue; retries with backoff on failure.
- Workbox Background Sync fires the drainer when connectivity returns.
Image caching:
Service worker intercepts image requests with a CacheFirst strategy (30-day TTL, max 1000 entries). Works best with download_images_enabled on your Wallabag instance.
Why the Worker exists #
Browsers enforce CORS. Wallabag doesn't consistently send Access-Control-Allow-Origin headers — especially on the OAuth endpoint and on error responses. Rather than requiring users to patch their Wallabag instance, Mathom routes all API calls through a Cloudflare Worker that adds the missing headers. The Worker does no authentication of its own and logs no request bodies.
Project layout #
mathom/
├── pwa/ # SvelteKit PWA (Cloudflare Pages)
│ ├── src/
│ │ ├── lib/
│ │ │ ├── api/ # Wallabag API client (framework-agnostic)
│ │ │ ├── db/ # Dexie schema and queries
│ │ │ ├── sync/ # Sync engine and mutation queue drainer
│ │ │ ├── components/ # Svelte components
│ │ │ └── stores/ # Svelte 5 rune-based state
│ │ ├── routes/
│ │ │ ├── +layout.svelte # Root layout (theme, font, global styles)
│ │ │ ├── +page.svelte # Article list (/?filter=unread|archived|starred|all)
│ │ │ ├── articles/[id]/ # Reader view
│ │ │ ├── settings/ # Settings + reader preferences
│ │ │ ├── settings/auth/ # Re-auth flow
│ │ │ ├── onboarding/ # First-time setup wizard
│ │ │ ├── search/ # Server-side search
│ │ │ └── share/ # Web Share Target endpoint (Android)
│ │ ├── sw.ts # Workbox service worker (vite-plugin-pwa, injectManifest)
│ │ └── app.html # HTML shell, includes manifest + icon links
│ ├── static/ # Icons, manifest assets, robots.txt
│ ├── .env.example # Environment variable template
│ ├── svelte.config.js
│ ├── vite.config.ts # Vite + vite-plugin-pwa config
│ └── package.json
├── worker/ # Cloudflare Worker (mathom-cors)
│ ├── src/index.ts # CORS proxy logic (~50 lines)
│ ├── wrangler.toml # Worker config and rate limiting
│ └── package.json
├── README.md
├── CLAUDE.md # Full product + technical specification
└── .gitignore
Common development tasks #
Running tests #
cd pwa && bun run test
The API client, DB layer, and sync engine are framework-agnostic and testable without a Svelte runtime.
Building for production #
# PWA
cd pwa && bun run build
# Output in pwa/.svelte-kit/output/
# Worker (dry run — shows what would be deployed)
cd worker && bunx wrangler deploy --dry-run
Bumping the Dexie schema version #
When you add or change a field on any Dexie table:
- Open
pwa/src/lib/db/schema.ts. - Add a new
db.version(N)call with the same store strings (or new ones if indexes change). - Chain
.upgrade(tx => { ... })to transform existing rows. Do not skip versions — Dexie runs migrations in order on upgrade.
this.version(2).stores({
entries: 'id, is_archived, is_starred, created_at, updated_at, cached_at',
pendingMutations: '++id, entry_id, type, created_at',
settings: 'id'
}).upgrade(async (tx) => {
await tx.table('settings').toCollection().modify((s) => {
s.last_full_sync_at = null;
});
});
Failing to bump the version when the schema changes causes a runtime error for users with existing data.
Adding a new route #
- Create
pwa/src/routes/your-route/+page.svelte(and+page.tsif you need a load function). - SvelteKit picks it up automatically. No router config needed.
- If the route needs data: use
+page.tswith aloadfunction (SSR is disabled;loadruns client-side only).
Adding a new Wallabag API call #
- Add the function to the appropriate file in
pwa/src/lib/api/. - Use the existing
apiFetchwrapper — it handles auth headers, token refresh on 401, and routing through the Worker. - Keep all API code framework-agnostic (no Svelte imports).
Updating the service worker / PWA manifest #
- Manifest: edit the
manifestobject inpwa/vite.config.tsunderVitePWA(...). - Custom SW logic:
pwa/src/sw.tsis the entry point — the project usesinjectManifest, so you own the SW source. Workbox precaches the build manifest, then individualregisterRoutecalls handle runtime caching. - Update flow:
registerType: 'prompt'shows users a "new version available" banner via the<UpdatePrompt />component. The SW does not callself.skipWaiting()automatically; updates apply when the user clicks Reload. - Regenerating PWA icons: edit
pwa/static/icon-source.svg, then runbunx --bun @vite-pwa/assets-generator --preset minimal-2023 static/icon-source.svgfrompwa/to regenerate all PNG variants.
After any SW change, the browser won't pick it up automatically during development. See below.
Debugging the service worker #
In Chrome DevTools:
- Application → Service Workers — see registration status, force update, unregister.
- Application → Cache Storage — inspect what Workbox has cached.
- Application → IndexedDB — inspect Dexie tables directly.
Common issue: SW not updating after a code change. Fix:
- DevTools → Application → Service Workers → click Unregister.
- Hard-reload (
Cmd+Shift+R/Ctrl+Shift+R). - Or run
bun run dev— Vite's dev mode bypasses the SW by default.
Deployment #
Deploy the CORS Worker #
cd worker
# First time: authenticate
bunx wrangler login
# Deploy
bunx wrangler deploy
Your Worker is live at https://mathom-cors.YOUR_ACCOUNT.workers.dev. Copy this URL — you'll need it for the PWA's PUBLIC_DEFAULT_WORKER_URL.
Deploy the PWA to Cloudflare Pages #
Manual:
cd pwa
bun run build
bunx wrangler pages deploy build --project-name=mathom
Via GitHub integration (recommended for production):
- In the Cloudflare dashboard: Pages → Create a project → Connect to Git.
- Select your repo.
- Build settings:
- Framework preset: SvelteKit
- Build command:
cd pwa && bun run build - Build output directory:
pwa/build
- Add environment variables (see below).
- Deploy.
Environment variables #
Set these in Cloudflare Pages → Settings → Environment variables:
| Variable | Value | Notes |
|---|---|---|
PUBLIC_DEFAULT_WORKER_URL |
https://mathom-cors.YOUR_ACCOUNT.workers.dev |
URL of your deployed Worker |
The Worker itself has no secrets — its wrangler.toml is the complete config.
Required Cloudflare setup #
- Free account is sufficient for both Pages and Workers.
- Workers: your account gets a
*.workers.devsubdomain automatically. - Pages: one project per app; the free tier allows unlimited deploys.
Trust and security #
What the Worker does #
- Receives a proxied request from the PWA with a
targetquery parameter (the full Wallabag API URL). - Validates that the target is HTTPS, points to a public hostname (not localhost or RFC1918), and has a path starting with
/api/or/oauth/. - Forwards the request method,
Authorizationheader,Content-Typeheader, and body. - Returns the Wallabag response with CORS headers added.
What the Worker does not do #
- Does not log request bodies. Auth credentials and article content are never logged.
- Does not authenticate users. It is a CORS shim, not a security boundary.
- Does not store anything. Stateless; no KV, no D1.
What credentials live where #
| Credential | Where stored | Notes |
|---|---|---|
| Wallabag access token | IndexedDB (device-local) | Short-lived; refreshed automatically |
| Wallabag refresh token | IndexedDB (device-local) | Persisted; cleared on logout |
| OAuth client ID / secret | IndexedDB (device-local) | Same trust model as Wallabag's mobile apps |
| Username / password | Nowhere (discarded after token exchange) | Never written to storage |
Self-hosting the Worker #
If you don't want to trust the project-hosted Worker:
- Clone this repo.
cd worker && bunx wrangler deploywith your own Cloudflare account.- Set your Worker's URL in Mathom's Settings → Advanced → Custom CORS proxy URL.
The Worker source is in worker/src/index.ts — ~50 lines, easy to audit.
Troubleshooting #
"I get CORS errors" #
- Confirm the Worker is running:
curl http://localhost:8787/should return a response (not a connection refused). - Check Worker URL in Mathom settings — must match exactly (
http://localhost:8787for local, no trailing slash). - If the error is on the OAuth endpoint specifically: this is a known Wallabag issue. The Worker handles it; if you're still seeing errors, check that your
worker_urlis set and that the Worker dev process is running.
"Tokens stop working / I get logged out" #
The app attempts a token refresh on every 401. If the refresh token is also expired or revoked (Wallabag default is 14 days for refresh tokens):
- Go to
/settings/auth. - Enter your password to re-authenticate.
- New tokens are issued and persisted.
"Service worker not updating" #
- Chrome DevTools → Application → Service Workers → Unregister.
- Hard-reload.
- Alternatively:
bun run devbypasses the SW in development mode — if you're seeing stale behaviour in dev, you may have a registered SW from a previous prod build. Unregister it.
"IndexedDB schema mismatch" / app crashes on load #
This happens when the Dexie schema version in code doesn't match the version in the user's browser. Fix:
- During development: open DevTools → Application → IndexedDB → delete the
mathomdatabase, reload. - In production: bump the version in
pwa/src/lib/db/schema.tsand write a migration. Never delete user data without explicit user action.
bunx wrangler crashes or hangs #
Fall back to Node:
# Install Node 20.x (e.g. via nvm or https://nodejs.org)
npx wrangler dev # or npx wrangler deploy
This is a known rough edge of running Wrangler outside its supported Node runtime.
Contributing #
Code style #
- TypeScript: strict mode everywhere. No
any. - Svelte: Svelte 5 runes only (
$state,$derived,$effect,$props). No legacy$:reactive declarations, nowritablestores. - CSS: plain CSS with custom properties. No Tailwind, no CSS-in-JS.
- Type checking:
bun run check(svelte-check). Fix all errors and warnings before opening a PR. - Tests:
bun run testfor the PWA,cd worker && bun run testfor the Worker. - File naming:
kebab-case.sveltefor components,kebab-case.tsfor modules.
Branch and commit conventions #
- Branch names:
feature/short-description,fix/short-description - Commit messages: imperative mood, present tense — "add reader font controls", not "added" or "adding"
- Keep commits focused; one logical change per commit
Filing an issue #
Use GitHub Issues. Include:
- Mathom version (or commit SHA)
- Browser and OS
- Wallabag version
- Steps to reproduce
- Expected vs actual behaviour
- Console errors if applicable