Desidero

A wishlist webapp focused on simplicity, speed, and reliability. Manage your collections, wishlist items, and more with an intuitive interface.

Features

• Collections Management: Organize your wishlist items into collections
• Wishlist Items: Add, edit, and track items with status updates
• Web Interface: Modern Astro-based web app with Tailwind CSS
• Authentication: Secure user authentication and profiles
• Real-time Updates: Live updates via tRPC
• Database: PostgreSQL with Drizzle ORM for scalable data storage

Tech Stack

• Frontend: Astro, React, Tailwind CSS, shadcn/ui
• Backend: tRPC, Node.js
• Database: PostgreSQL with Drizzle ORM
• Runtime: Bun
• Validation: Zod
• Authentication: Better Auth with magic link emails
• Email: Nodemailer with SMTP support

Installation

1. Clone the repository:

   git clone <repository-url>
   cd desidero
   

2. Install dependencies:

   bun install
   

3. Set up the database:

   bun run db:push
   

4. Configure environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   

5. Start the development server:

   bun run dev
   

Configuration

Environment Variables

Copy .env.example to .env and configure the following variables:

Required

• DATABASE_URL: PostgreSQL connection string
• AUTH_SECRET: Random secret key for authentication

Optional

• DEFAULT_ADMIN_EMAIL: Email for default admin user (created on boot)
• DEFAULT_ADMIN_NAME: Name for default admin user (defaults to "Admin")
• DISABLE_SIGNUP: Disable user registration (set to "true" to disable)
• SENTRY_DSN: Sentry DSN for error tracking (enables Sentry if provided)
• SENTRY_AUTH_TOKEN: Sentry auth token for releases and source maps

Email Configuration (Required for magic link authentication)

Configure SMTP settings for sending magic link emails:

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
EMAIL_FROM=noreply@yourdomain.com

# Development mode (prints emails to console instead of sending)
EMAIL_PRINT_MODE=true

Supported SMTP Providers

• Gmail: smtp.gmail.com:587 (use app password, not regular password)
• SendGrid: smtp.sendgrid.net:587 (use API key as password)
• Mailgun: smtp.mailgun.org:587
• AWS SES: email-smtp.region.amazonaws.com:587
• Custom SMTP: Any SMTP server that supports STARTTLS

Development Mode

Set EMAIL_PRINT_MODE=true to print emails to console instead of sending them. This is useful for development and testing.

Default Admin User

Configure the following environment variables to automatically create a default admin user when the application starts:

DEFAULT_ADMIN_EMAIL=admin@yourdomain.com
DEFAULT_ADMIN_NAME=Admin

If these variables are set, the application will:

1. Check if an admin user with the specified email already exists
2. Create the admin user if it doesn't exist
3. Set the user's role to "admin"
4. Log the creation status to the console

This is useful for:

• Development environments
• Initial deployment setup
• Automated deployments where you need a known admin account

Sentry Error Tracking (Optional)

Configure Sentry for error tracking and performance monitoring:

SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_AUTH_TOKEN=your-sentry-auth-token

If SENTRY_DSN is provided, Sentry will be automatically enabled with:

• Error tracking for both client and server
• Performance monitoring with traces
• Session replay for debugging
• Automatic source map uploads for production builds

The integration is completely optional - if SENTRY_DSN is not set, Sentry will not be loaded at all.

Usage

Web App

Visit http://localhost:4321 to access the web interface.

Development

Available Scripts

• bun run dev - Start Astro dev server
• bun run build - Build for production
• bun run preview - Preview production build
• bun check - TypeScript check
• bun run db:push - Push database schema changes

Project Structure

src/
├── server/       # tRPC API and database
│   ├── api/routers/  # tRPC routers
│   └── db/       # Database schema and connections
└── web/          # Astro web application
    ├── components/  # React components
    ├── layouts/     # Astro layouts
    ├── pages/       # Astro pages
    └── styles/      # Global styles

Code Style

• Use tabs for indentation
• camelCase for variables and functions
• Explicit return types for functions
• Path mappings: ~/server/*, ~/web/*
• Keep files under 200 lines
• Follow existing patterns and conventions

Contributing

1. Follow the development guidelines in docs/RULES.md
2. Use the Backlog.md CLI for task management
3. Keep changes atomic and focused
4. Run tests and linting before committing
5. Update documentation as needed

License

MIT License - see LICENSE file for details