A modern, shareable grocery list app that stores everything in the URL. No accounts, no databases, just pure convenience.
- Your entire grocery list lives in the URL
- Share lists instantly by copying and pasting the URL
- No sign-ups or accounts required
- Works across all devices and browsers
- To Buy - Your active shopping list
- Favorites - Items you buy regularly
- Never Buy - Items to avoid (allergies, dislikes, etc.)
- 7 store categories: Produce, Dairy, Meat, Bakery, Frozen, Pantry, Household
- Color-coded category icons for quick identification
- Search and filter by category
- Mark items as purchased while shopping
- Responsive design optimized for phone use while shopping
- Touch-friendly interface
- Works offline (once loaded)
- PWA-ready for home screen installation
- Move items between lists with one tap
- Add items from Favorites to your To Buy list
- Import grocery lists from markdown files
- Compressed URLs keep links shareable even with large lists
- Real-time URL updates as you modify your list
- Node.js 18+
- npm or pnpm
-
Clone the repository
git clone https://github.com/pglevy/FamilyListPro.git cd FamilyListPro -
Install dependencies
npm install
-
Start development server
npm run dev
The app will be available at
http://localhost:5173 -
Start the backend (in a separate terminal)
npm run dev:server
The API will be available at
http://localhost:5000
npm run build
npm startFamily List Pro uses a unique architecture where all your grocery data is stored in the URL hash using advanced compression:
- State Compression - Item data is compressed using field shortening and LZ-string compression
- URL Storage - Compressed data is stored in the URL hash for instant sharing
- Smart Filtering - Only "To Buy" items are included in shareable URLs to keep them shorter
- Real-time Sync - URL updates automatically as you modify your list
https://yoursite.com/#groceryItems=<compressed-data>&tab=tobuy&share=<shareable-data>
- Click the "+" button to open the add item modal
- Enter item name, select category, and add optional notes
- Choose which list to add it to (To Buy, Favorites, or Never Buy)
- To Buy List: Your active shopping list with purchase tracking
- Favorites: Frequently bought items - click to add to To Buy list
- Never Buy: Items to avoid - helps with family dietary restrictions
- Click the share button in the header
- Copy the URL from your browser
- Share via text, email, or any messaging app
- Recipients see your current To Buy list
Items are organized by store sections:
- 🥬 Produce - Fruits, vegetables, fresh items
- 🥛 Dairy - Milk, cheese, yogurt, eggs
- 🥩 Meat - All proteins and deli items
- 🥖 Bakery - Bread, pastries, baked goods
- 🧊 Frozen - Frozen foods and ice cream
- 🥫 Pantry - Shelf-stable items, canned goods
- 🧴 Household - Cleaning supplies, paper products
FamilyListPro/
├── client/ # React frontend
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── context/ # React context
│ │ ├── hooks/ # Custom hooks
│ │ └── lib/ # Utilities
├── server/ # Express backend
├── shared/ # Shared types
└── CLAUDE.md # AI assistant guidelines
- Frontend: React 18, TypeScript, Tailwind CSS, Vite
- Backend: Express.js, TypeScript
- UI Components: Radix UI primitives with shadcn/ui
- State Management: React Context + Custom URL hooks
- Compression: LZ-string for efficient URL storage
npm run dev- Start frontend development servernpm run dev:server- Start backend development servernpm run build- Build for productionnpm run check- Type checkingnpm start- Start production server
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with shadcn/ui components
- Icons from Font Awesome
- Compression powered by LZ-string
Happy Shopping! 🛒✨