Before It's Gone by AetherAssembly

An offline-first app, available as a desktop (Electron) app or self-hosted PWA, that tracks what's in your fridge, freezer, and pantry before it expires. No account required; all data stays on your device.

Download GitHub → GitLab mirror →

Features

Inventory

• Barcode scanning with local profile storage and Open Food Facts lookup: product name, category, kcal/100g, and allergens filled in automatically.
• Expiry date tracking with shelf-life presets; dates are stored accurately and never recalculated.
• Color-coded cards: amber (expiring soon) · rose (expired). Desktop notifications warn you before things go bad or run low.
• Search, filter, and sort: find items by name, barcode, or category; filter by location; sort by expiry date, date added, or name.
• Tag filtering: click any tag chip to narrow the list (AND semantics).
• Stats dashboard: expiring this week · expiring soon · expired · total units at a glance; collapsible charts by location, by category, and a 7-day expiry countdown.
• Expiry timeline view: toggle from list view to a horizontal timeline showing all items color-coded by status.
• Item photos: attach a photo to any item; thumbnail shown on the card, full image in the detail drawer.
• Item detail drawer: click any card to open a slide-in drawer with all fields and an inline edit form.
• Quantity management: − Use one with low-stock alerts · + Add one · 5-second undo toast.
• Recurring items: auto-restock to a configured quantity when an item is depleted to zero.
• Quick-add buttons: re-add things you buy often from item history in one click.
• Bulk select: delete or move multiple items at once; clear all with a confirmation guard.
• Drag-and-drop: drag any card onto a location chip above the grid to move it instantly.
• Keyboard shortcuts: N add item · / search · Esc close drawer · ? show shortcut list.
• Custom storage locations: add locations beyond the built-in fridge / freezer / pantry.

Lists & tracking

• Shopping list: auto-populated from items below their low-stock threshold; copy or export as plain text.
• Waste log: expired items are logged when deleted, grouped by month, and clearable.
• Recipe suggestions: dismissible banner of TheMealDB recipes when 3+ items are expiring.

Scanner

• In-browser barcode scanner (PWA): when accessing the self-hosted PWA from a phone or tablet, a Scan barcode button opens the device camera directly via @zxing/browser, with no QR relay needed.
• Phone barcode scanner (desktop): scan a QR code on any phone browser to open a camera page that feeds barcodes into the desktop app.
• Manual expiry date: on the phone review card overrides the shelf-life prediction; date and days fields stay in sync.

UI

• Dark and light mode: toggle in the header, persisted across sessions.
• Animated background: subtle hue-shift animation on the background.
• Glass panels: frosted glass effect on all panels via backdrop-filter.
• Toast notifications: success, warning, and error toasts; auto-dismiss after 3 seconds.
• Responsive layout: controls stack vertically on narrow screens; 44 px touch targets.
• Loading skeletons: shimmer placeholder cards shown while inventory loads.

Settings & data

• Settings panel: default location, default shelf life, expiry warning window (configurable days), per-type notification toggles.
• Import and export: back up to JSON or CSV; import from JSON or CSV; batch barcode import from a plain-text file (one barcode per line, enriched via Open Food Facts).
• Email notifications: optional daily/weekly digest and alerts via Resend or SMTP; pause/snooze controls; HTML templates. Desktop app only.
• Optional cloud sync: bring your own Supabase project; offline-first by default; last-write-wins merge; no mandatory account.

Stack

Platforms

See the Installation page for step-by-step instructions.

Self-Hosted PWA

Run Before It's Gone as an installable Progressive Web App on any device on your LAN or Tailscale network, with no Electron required. Barcode scanning uses the device camera directly in the browser.

# Generate a self-signed certificate (run once)
mkdir -p docker/certs
openssl req -x509 -newkey rsa:4096 -keyout docker/certs/key.pem \
  -out docker/certs/cert.pem -days 3650 -nodes \
  -subj "/CN=before-its-gone-local"

# Build and start
npm run docker:pwa:up

Open https://<your-server-ip> from any device on the same network. Use the browser's Add to Home Screen prompt to install it as an app. For Tailscale, run tailscale cert <hostname> to provision a trusted cert and avoid the self-signed warning.

Development

Prerequisites

• Node.js >= 22.12.0
• npm >= 10

Setup

git clone https://github.com/AetherAssembly/Before-Its-Gone.git
cd Before-Its-Gone
npm install

Run

npm run dev              # Electron app with hot reload
npm run dev:web          # Web only: binds to 0.0.0.0:5173 (LAN-accessible)

On Linux the app auto-detects Wayland. To override:

BIG_LINUX_DISPLAY_BACKEND=x11 npm run dev      # force X11
BIG_LINUX_DISPLAY_BACKEND=wayland npm run dev  # force Wayland

Test

npm run test             # unit tests (packages/core)
npm run test:coverage    # with branch coverage report (target: ≥ 80%)

Build & package

npm run build                      # compile only
npm run package:linux              # → AppImage + .deb + .rpm (x86_64)
npm run package:linux:arm64        # → AppImage + .deb + .rpm (arm64, cross-compiled)
npm run package:macos              # → DMG  (run on macOS)
npm run package:windows            # → .exe  (run on Windows)
npm run docker:pwa:up              # build and start self-hosted PWA container
npm run docker:pwa:down            # stop the container

npm Packages

The core logic and UI component are published to GitHub Packages for use in your own projects.

# configure npm to use GitHub Packages for @aetherAssembly
echo "@aetherAssembly:registry=https://npm.pkg.github.com" >> .npmrc

npm install @aetherAssembly/core
npm install @aetherAssembly/ui

Docs

• Installation: platform-specific install and uninstall instructions
• Import & Export Format: JSON and CSV field reference, examples, barcode import
• Email Notifications: Resend and SMTP setup, digest scheduling, pause/snooze
• Cloud Sync: Supabase project setup, SQL migration, sync behaviour
• API Setup: Open Food Facts and TheMealDB integration details
• Architecture: monorepo layout, storage map, IPC channels, build pipeline
• SMTP Config: SMTP provider guide
• Data Model: InventoryItem field reference
• Self-Hosting: run as a PWA via Docker and nginx
• Changelog: full version history

Privacy

By default, all data is stored locally in IndexedDB, with no account required. Optional features make additional outbound requests:

• Barcode lookup: Open Food Facts receives the barcode value you scan. User-triggered only.
• Recipe suggestions: TheMealDB receives the name of an expiring item as an ingredient query. Fires automatically when 3+ items are expiring; dismissible.
• Email notifications: your chosen provider (Resend or your own SMTP server) receives item names and expiry data to compose digest emails. Credentials are stored locally in userData/email-settings.json.
• Cloud sync: your Supabase project receives your full inventory. Opt-in only; disabled by default.

See PRIVACY_POLICY.md for the full policy.