wishlist/wishlist-app/README.md

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)

docker-compose up -d
docker-compose exec app bun run db:push

Visit http://localhost:3000 🎉

See DOCKER.md for complete Docker documentation.

📚 Deployment Guides

• COOLIFY_DEPLOYMENT.md - Deploy to Coolify (recommended for production)
• DOCKER.md - Docker & docker-compose guide
• SETUP.md - Local development setup

Prerequisites

• Bun installed (for local development)
• PostgreSQL database (local, Docker, or hosted)
• Docker (optional, for containerized deployment)

Getting Started (Local Development)

1. Install Dependencies

bun install

2. Set Up Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Edit .env and add your PostgreSQL connection string:

DATABASE_URL=postgresql://username:password@localhost:5432/wishlist

3. Set Up the Database

Push the database schema (easiest for development):

bun run db:push

Or use migrations (recommended for production):

bun run db:generate
bun run db:migrate

4. Start the Development Server

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 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

bun run build

Preview Production Build

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