228 lines
5.9 KiB
Markdown
228 lines
5.9 KiB
Markdown
# Wishlist App
|
|
|
|
A simple, self-contained wishlist application built with SvelteKit, Tailwind CSS, Drizzle ORM, and PostgreSQL. Create wishlists and share them with friends and family via secure links.
|
|
|
|
## Features
|
|
|
|
- 🎁 Create wishlists with items (title, description, links, images, prices, priorities)
|
|
- 🔗 Two types of links:
|
|
- **Owner Link**: Edit and manage your wishlist
|
|
- **Public Link**: Share with friends to view and reserve items
|
|
- 🔒 Link-based security (no accounts required)
|
|
- 👥 Reserve items with optional name
|
|
- 📱 Fully responsive mobile design
|
|
- 🎨 Clean, modern UI with shadcn components
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: SvelteKit 2 with Svelte 5
|
|
- **Styling**: Tailwind CSS v4
|
|
- **Database**: PostgreSQL with Drizzle ORM
|
|
- **UI Components**: shadcn-svelte
|
|
- **Runtime**: Bun
|
|
- **TypeScript**: Full type safety
|
|
|
|
## Quick Start
|
|
|
|
### 🐳 Docker (Recommended for Quick Testing)
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
docker-compose exec app bun run db:push
|
|
```
|
|
|
|
Visit `http://localhost:3000` 🎉
|
|
|
|
See [DOCKER.md](./DOCKER.md) for complete Docker documentation.
|
|
|
|
### 📚 Deployment Guides
|
|
|
|
- **[COOLIFY_DEPLOYMENT.md](./COOLIFY_DEPLOYMENT.md)** - Deploy to Coolify (recommended for production)
|
|
- **[DOCKER.md](./DOCKER.md)** - Docker & docker-compose guide
|
|
- **[SETUP.md](./SETUP.md)** - Local development setup
|
|
|
|
## Prerequisites
|
|
|
|
- [Bun](https://bun.sh/) installed (for local development)
|
|
- PostgreSQL database (local, Docker, or hosted)
|
|
- Docker (optional, for containerized deployment)
|
|
|
|
## Getting Started (Local Development)
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
### 2. Set Up Environment Variables
|
|
|
|
Create a `.env` file in the root directory:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and add your PostgreSQL connection string:
|
|
|
|
```env
|
|
DATABASE_URL=postgresql://username:password@localhost:5432/wishlist
|
|
```
|
|
|
|
### 3. Set Up the Database
|
|
|
|
Push the database schema (easiest for development):
|
|
|
|
```bash
|
|
bun run db:push
|
|
```
|
|
|
|
Or use migrations (recommended for production):
|
|
|
|
```bash
|
|
bun run db:generate
|
|
bun run db:migrate
|
|
```
|
|
|
|
### 4. Start the Development Server
|
|
|
|
```bash
|
|
bun run dev
|
|
```
|
|
|
|
The app will be available at `http://localhost:5173`
|
|
|
|
## Database Commands
|
|
|
|
- `bun run db:generate` - Generate new migration from schema changes
|
|
- `bun run db:migrate` - Run migrations
|
|
- `bun run db:push` - Push schema directly to database (development)
|
|
- `bun run db:studio` - Open Drizzle Studio to browse your database
|
|
|
|
## How It Works
|
|
|
|
### Creating a Wishlist
|
|
|
|
1. Visit the home page
|
|
2. Enter a title and optional description
|
|
3. Click "Create Wishlist"
|
|
4. You'll be redirected to the owner edit page with your unique owner link
|
|
|
|
### Managing Your Wishlist (Owner)
|
|
|
|
- Add items with details (name, description, URL, image, price, priority)
|
|
- Delete items
|
|
- See which items have been reserved (but not who reserved them for surprise protection)
|
|
- Share the public link with friends and family
|
|
- Keep your owner link private to maintain edit access
|
|
|
|
### Viewing and Reserving Items (Public)
|
|
|
|
- Open the public link shared by the wishlist owner
|
|
- Browse available items
|
|
- Click "Reserve This" on any item to claim it
|
|
- Optionally add your name so others can coordinate
|
|
- Cancel your reservation if plans change
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── lib/
|
|
│ ├── components/ui/ # shadcn-svelte components
|
|
│ ├── server/
|
|
│ │ ├── db.ts # Database connection
|
|
│ │ └── schema.ts # Drizzle schema definitions
|
|
│ └── utils.ts # Utility functions
|
|
├── routes/
|
|
│ ├── api/wishlists/ # API endpoints
|
|
│ ├── wishlist/[token]/ # Public view page
|
|
│ │ └── edit/ # Owner edit page
|
|
│ └── +page.svelte # Home page
|
|
└── app.css # Global styles with Tailwind
|
|
```
|
|
|
|
## Database Schema
|
|
|
|
### wishlists
|
|
- `id` - UUID primary key
|
|
- `title` - Wishlist title
|
|
- `description` - Optional description
|
|
- `ownerToken` - Unique token for editing
|
|
- `publicToken` - Unique token for viewing
|
|
- `createdAt`, `updatedAt` - Timestamps
|
|
|
|
### items
|
|
- `id` - UUID primary key
|
|
- `wishlistId` - Foreign key to wishlists
|
|
- `title` - Item name
|
|
- `description` - Optional description
|
|
- `link` - Optional product URL
|
|
- `imageUrl` - Optional image URL
|
|
- `price` - Optional price
|
|
- `priority` - high | medium | low
|
|
- `isReserved` - Boolean flag
|
|
- `createdAt`, `updatedAt` - Timestamps
|
|
|
|
### reservations
|
|
- `id` - UUID primary key
|
|
- `itemId` - Foreign key to items
|
|
- `reserverName` - Optional name of person who reserved
|
|
- `createdAt` - Timestamp
|
|
|
|
## Security Considerations
|
|
|
|
- Links use cryptographically secure random IDs (cuid2)
|
|
- Owner and public tokens are separate and unique
|
|
- No authentication system means links should be treated as passwords
|
|
- Owner links should be kept private
|
|
- Public links can be shared freely
|
|
|
|
## Deployment
|
|
|
|
### Coolify (Docker) - Recommended
|
|
|
|
This application includes a Dockerfile optimized for Coolify deployment.
|
|
|
|
📖 **See [COOLIFY_DEPLOYMENT.md](./COOLIFY_DEPLOYMENT.md) for complete deployment guide**
|
|
|
|
Quick steps:
|
|
1. Push code to Git repository
|
|
2. Create PostgreSQL database in Coolify
|
|
3. Create new application in Coolify
|
|
4. Set `DATABASE_URL` environment variable
|
|
5. Deploy and run `bun run db:push` to set up schema
|
|
|
|
### Build for Production
|
|
|
|
```bash
|
|
bun run build
|
|
```
|
|
|
|
### Preview Production Build
|
|
|
|
```bash
|
|
bun run preview
|
|
```
|
|
|
|
### Other Platforms
|
|
|
|
This app uses `@sveltejs/adapter-node` for Docker/Node.js deployments, but can be adapted for:
|
|
|
|
- **Vercel/Netlify**: Change to `@sveltejs/adapter-auto`
|
|
- **Cloudflare Pages**: Use `@sveltejs/adapter-cloudflare`
|
|
- **Static**: Use `@sveltejs/adapter-static` (requires API route adjustments)
|
|
|
|
Make sure to set your `DATABASE_URL` environment variable in your deployment platform.
|
|
|
|
## Development
|
|
|
|
- All components are fully typed with TypeScript
|
|
- UI components follow shadcn-svelte patterns
|
|
- Mobile-first responsive design using Tailwind
|
|
- Server-side rendering for better performance and SEO
|
|
|
|
## License
|
|
|
|
MIT
|