ExpLogger

A zero-backend PWA expense tracker. Monthly expenses are committed as JSON files to a private GitHub repo via the Contents API. No server, no subscription.

---

Two repos you need on GitHub

Repo	Visibility	Purpose
explogger	Public	This code — hosted on GitHub Pages
my-expenses (or any name)	Private	Expense data files

---

Local development

npm install      # installs deps; predev script generates PWA icons
npm run dev      # http://localhost:5173

On first load you'll see the Connect Repository screen. Enter:

• Repository: yourname/my-expenses

• PAT: a fine-grained Personal Access Token scoped to that repo

  → GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
  → Repository access: my-expenses only
  → Permissions: Contents → Read and write

---

Deploy to GitHub Pages

1. Push to main — the Actions workflow builds and deploys automatically.
2. First time only: enable Pages in the repo settings:
   Settings → Pages → Source → GitHub Actions
3. Your app URL: https://YOUR_USERNAME.github.io/explogger/

---

Install as a PWA

Android (Chrome)
Open the URL → three-dot menu → Add to Home screen / Install app

iOS (Safari)
Open the URL → Share sheet → Add to Home Screen

---

Data format

Expenses live in expenses-YYYY-MM.json in your data repo:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "date": "2026-05-24",
    "amount": 12.50,
    "category": "food",
    "note": "lunch"
  }
]

---

Offline behaviour

• The app shell is cached by the service worker — it loads instantly even with no signal.
• Expenses logged offline are stored in localStorage and committed to GitHub automatically when the connection returns.
• The Sync chip in the top-right shows pending count and lets you force-sync manually.

---

Regenerate icons

node generate-icons.mjs --force