initial working version
This commit is contained in:
227
wishlist-app/README.md
Normal file
227
wishlist-app/README.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user