A modern, full-stack library management system built with React, TypeScript, Node.js, and PostgreSQL. Perfect for small to medium-sized libraries, schools, community centers, or personal book collections.
🎯 Production-Ready • ✅ 486 Tests Passing • 🚀 Docker-Ready • 📖 Well-Documented
- Book Management: Add, edit, search books with ISBN lookup (Google Books/Open Library API)
- Netflix-Style Grid View: Visual book browsing with cover images, hover animations, and detailed modals
- Book Descriptions: Add synopsis/descriptions to books (auto-populated from ISBN lookup)
- Bulk Operations (Admin): Multi-select books for bulk delete, update availability, or manage categories
- Member Management: Track library members with contact information
- Loan System: Automated 14-day loan periods with overdue tracking
- Categories: Organize books with multi-category support
- Cover Images: Upload and display book covers
- 🌐 Unicode/Multilingual: Full support for Malayalam, Hindi, Tamil, and other languages in CSV import/export
- JWT-based authentication with role-based access (Admin/Member)
- Proactive Token Validation: Automatic expiration checking on page load and every 60 seconds
- Bcrypt password hashing with timing-attack protection
- Rate limiting (5 req/15min for auth, 100 req/15min for API)
- Helmet security headers with Content Security Policy
- XSS protection with comprehensive input sanitization
- CORS configuration for production security
- Dashboard: Real-time statistics (books, members, active loans, overdue)
- User Management: Create and manage admin/member accounts
- Data Export: CSV exports with date filters (UTF-8 with BOM for Excel/LibreOffice)
- Bulk Import: CSV import for books and members (supports Unicode/Malayalam)
- Bulk Operations: Multi-select books for bulk actions (delete, update, categorize)
- Floating Action Toolbar: Quick access to bulk operations when items are selected
- System Info: View configuration and database status
- Responsive Design: Mobile-first with Tailwind CSS v4
- Grid & Table Views: Toggle between Netflix-style visual grid and detailed table view
- Book Detail Modal: Click any book for detailed view with cover, description, and actions
- Dark/Light Theme: User preference saved to localStorage
- Smooth Animations: Framer Motion for delightful interactions (hover, transitions, loading)
- Accessibility: ARIA labels, keyboard navigation, screen reader support
- Loading States: Skeletons and loading indicators
- User Onboarding: Feature tour for new users
- Database Optimization: 9 indexes for 10-100x query performance
- Optimized Queries: Dashboard uses single query (75% faster)
- Connection Pool: Tuned for production workloads
- Load Tested: Validated for 100+ concurrent users
- Error Monitoring: Sentry integration ready (optional)
- Request Tracing: UUID-based request IDs for debugging
- Node.js 20+
- PostgreSQL 14+
- pnpm 10+ (or npm/yarn)
- Docker (optional, recommended)
# Clone the repository
git clone <https://github.com/pranavp1507/homeshelf.git>
cd homeshelf
# Start with Docker Compose
docker-compose -f compose.dev.yml up -d
# Access the application
# Frontend: <http://localhost:3000>
# Backend API: <http://localhost:3001/api>
First-time setup will prompt you to create an admin account.
# 1. Clone and install dependencies
git clone <https://github.com/pranavp1507/homeshelf.git>
cd homeshelf
# Install server dependencies
cd server
pnpm install
# Install client dependencies
cd ../client
pnpm install
# 2. Setup PostgreSQL database
createdb library
# 3. Configure environment variables
cd ../server
cp .env.example .env
# Edit .env with your database credentials and JWT secret
# 4. Run database migrations
pnpm run migrate up
# 5. Start the backend server
pnpm run dev # Runs on <http://localhost:3001>
# 6. Start the frontend (new terminal)
cd ../client
pnpm run dev # Runs on <http://localhost:3000>Visit http://localhost:3000\ and create your admin account!
- Getting Started Guide - Detailed setup instructions
- Customization Guide - Configure branding, features, and settings
- Unicode/Multilingual CSV Guide - Malayalam, Hindi, Tamil support with Excel/LibreOffice
- API Documentation - REST API endpoints reference
- Testing Guide - Running and writing tests
- Contributing Guide - How to contribute to this project
- Technical Documentation - Architecture and development details
- React 19.0 + TypeScript
- Vite 7.2 - Lightning-fast build tool
- Tailwind CSS v4 - Utility-first styling
- Framer Motion - Smooth animations
- Vitest + React Testing Library - Unit testing
- Playwright - E2E testing
- Node.js 24 + TypeScript
- Express 5.1 - Web framework
- PostgreSQL 16 - Relational database
- JWT - Authentication
- Bcrypt - Password hashing
- Jest + Supertest - Testing
- Docker + Docker Compose - Containerization
- Traefik - Reverse proxy with HTTPS
- k6 - Load testing
- Sentry - Error monitoring (optional)
- GitHub Actions - CI/CD ready
This project has comprehensive test coverage:
# Run all tests
pnpm test:all
# Client tests (160 tests)
cd client && pnpm test
# Server tests (326 tests)
cd server && pnpm test
# E2E tests (47 tests)
pnpm test:e2e
# Load testing
cd server && pnpm test:smoke # 30-second smoke test
cd server && pnpm test:load # 16-minute load testTotal Coverage: 486 tests (100% passing) ✅
- Development (`compose.dev.yml`) - Simple localhost HTTP, no certificates needed
- Local HTTPS (`compose.yml`) - Traefik with self-signed certs (requires certificate setup)
- Production (`compose.prod.yml`) - Let's Encrypt SSL for real domains
- GitHub Container Registry (`compose.ghcr.yml`) - Pre-built images, fastest setup! ⚡
For Local HTTPS with compose.yml:
# 1. Generate self-signed certificates
mkdir -p traefik/certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout traefik/certs/key.pem \
-out traefik/certs/cert.pem \
-subj "/CN=homelib.local"
# 2. Add hostname to hosts file
# Linux/Mac:
echo "127.0.0.1 homelib.local" | sudo tee -a /etc/hosts
# Windows (as Administrator):
# Add-Content C:\Windows\System32\drivers\etc\hosts "127.0.0.1 homelib.local"
# 3. Copy and configure .env
cp .env.example .env
# Edit .env with your JWT_SECRET and passwords
# 4. Start with Traefik
docker-compose -f compose.yml up --build -d
# Access: https://homelib.local (accept browser warning for self-signed cert)For Production with Let's Encrypt:
# 1. Point your domain DNS to your server's public IP
# 2. Copy and configure .env
cp .env.example .env
# Edit .env and set:
# - PRODUCTION_DOMAIN=your-domain.com
# - LETSENCRYPT_EMAIL=your-email@example.com
# - JWT_SECRET and POSTGRES_PASSWORD
# 3. Create acme.json for Let's Encrypt
touch traefik/acme.json
chmod 600 traefik/acme.json
# 4. Open firewall ports 80 and 443
# 5. Start production deployment
docker-compose -f compose.prod.yml up --build -d
# Access: https://your-domain.com
# Note: Test with staging first to avoid Let's Encrypt rate limits
# Uncomment the staging CA server line in compose.prod.ymlThe easiest way to deploy HomeShelf is using pre-built images from GitHub Container Registry:
# 1. Copy and configure environment file
cp .env.ghcr.example .env
# Edit .env - set JWT_SECRET and database password
# 2. Start the application
docker-compose -f compose.ghcr.yml up -d
# 3. Access at <http://localhost:3000>
Available Images:
ghcr.io/pranavp1507/homeshelf-client:latest- React frontendghcr.io/pranavp1507/homeshelf-server:latest- Node.js backend
Images are automatically built and published via GitHub Actions on every release.
📝 Note on Branding: Pre-built images use default "HomeShelf" branding. To customize the library name and logo, see Customization Options below or refer to the Customization Guide.
Key environment variables to configure (see .env.ghcr.example):
Required:
JWT_SECRET=your-super-secret-jwt-key-min-32-chars # Generate with: openssl rand -hex 32
POSTGRES_PASSWORD=secure_database_passwordOptional:
# Ports (host-side only, internal ports are fixed)
CLIENT_PORT=3000
SERVER_PORT=3001
POSTGRES_PORT=5432
# Google Books API for ISBN lookup
GOOGLE_BOOKS_API_KEY=your-api-key
# Email notifications (optional)
ENABLE_EMAIL_NOTIFICATIONS=false
SMTP_HOST=smtp.gmail.com
SMTP_USER=<your-email@gmail.com>
SMTP_PASSWORD=your-app-passwordSee .env.ghcr.example for all available configuration options.
HomeShelf supports branding customization (library name and logo), but the method depends on your deployment approach:
- Method: Use
compose.ghcr.yml - Branding: Fixed as "HomeShelf" with default logo
- Best for: Quick deployment, don't need custom branding
- Method: Use
compose.ymlorcompose.dev.yml - Branding: Fully customizable via
.env - Steps:
- Copy
.env.exampleto.env - Set
VITE_LIBRARY_NAME=Your Library - Set
VITE_LIBRARY_LOGO=/your-logo.svg - Add logo to
client/public/ - Run
docker-compose up --build
- Copy
- Method: Fork repository, configure GitHub Actions
- Branding: Customizable via repository variables
- Best for: Multiple deployments with same branding
For detailed instructions, see: Customization Guide
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Run tests (
pnpm test:all) - Commit with conventional commits (
git commit -m 'feat: add amazing feature') - Push to your fork (
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 Claude Code
- Icons from Heroicons
- UI inspired by modern library systems
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Full Documentation
- Mobile app (React Native)
- Book reservations system
- Fine management for overdue books
- Email notifications (SMTP configured)
- Barcode scanner support
- Multi-language support
- Analytics dashboard
- API versioning (v2)