ShelfTick

A compact dashboard to track expiration dates and get reminded before items expire. I use it to track anything that expires, needs replacing, or should be reviewed by a certain date:

• Pantry and household stock: Canned tomatoes, beans, flour, coffee, pet food, water filters, and others, so older item are used first
• Documents and renewals: Passports, driving licenes, visas, permits, insurance policies, certificates
• Safety and maintenance: Smoke-alarm batteries, fire extinguishers, first-aid kits, emergency supplies, air filters, water-filter cartridges
• Health and personal care: Medicine, sunscreen, cosmetics, COVID test kits
• Warranties and services: Warranty periods, software licenes, domain renewals, memberships, subscriptions, recurring service dates

ShelfTick sorts items by expiration date and separates those that need attention from those that are fine for now. Each item can have its own lead time and quantity. For example:

Stack

• Frontend: Website using React, TypeScript, Vite, Tailwind CSS
• Backend: REST API using Django and Django REST Framework
• Database: PostgreSQL

Local setup

Requires Python 3.14+, uv, Node.js with npm, and PostgreSQL.

Create a PostgreSQL database and user, then configure the backend:

cp backend/.env.example backend/.env

Edit backend/.env with your database credentials and a local Django secret key. Then start the API:

cd backend
uv sync
uv run python manage.py migrate
uv run python manage.py runserver

In another terminal, start the frontend:

cd frontend
npm install
npm run dev

Open http://localhost:5173.

After the initial setup, run make backend and make frontend from the repository root to start the two development servers.

Demo data

From the repository root:

make demo-data

To replace all existing items, use make demo-data-reset. The command asks for confirmation before deleting data.

Email reminders

ShelfTick can send one email digest containing non-expired items whose individual lead time has been reached. Configure the SHELFTICK_REMINDER_*, DEFAULT_FROM_EMAIL, and EMAIL_* values in backend/.env, then run:

make send-reminders

ShelfTick does not run a scheduler itself. Run this command manually or invoke it from cron or another scheduler at the desired frequency; each invocation sends the current digest when qualifying items exist.

Testing

make backend-check
make frontend-check

License

ShelfTick is licensed under the Apache License 2.0.

Attributions:

• The edit and delete icons are adapted from Feather, copyright (c) 2013-2023 Cole Bemis, and used under the MIT License.
• Codex assisted me for creating the logo and the frontend Tailwind design.