GitHub

Developer Quickstart

Follow this comprehensive guide to set up Mail Assist in your local development environment.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js - Version 18.17 or later
  • npm - Version 9 or later (comes with Node.js)
  • Git - For cloning the repository
Version Check
Run node --version and npm --version to verify your installations.

Installation

Step 1: Clone the Repository

git clone https://github.com/yourusername/mail-assist.git
cd mail-assist

Step 2: Install Dependencies

npm install

This will install all required dependencies including:

  • Next.js and React
  • TypeScript
  • Tailwind CSS
  • ShadCN/UI components
  • Supabase client
  • Resend SDK

Environment Setup

Step 3: Configure Environment Variables

Copy the example environment file:

cp .env.example .env.local

Open .env.local and configure the following variables:

.env.local
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Resend Configuration
RESEND_API_KEY=your_resend_api_key

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

Setting up Supabase

  1. Go to supabase.com and create a new project
  2. Navigate to Settings → API
  3. Copy your Project URL and anon public key
  4. Copy your service role key (keep this secret!)
Security Note
Never commit your .env.local file to version control. The service role key has admin privileges and should be kept secure.

Setting up Resend

  1. Sign up at resend.com
  2. Verify your domain (or use the sandbox domain for testing)
  3. Generate an API key from the dashboard
  4. Add the API key to your environment variables

Database Setup

Step 4: Set up Database Tables

Run the following SQL in your Supabase SQL editor to create the required tables:

database-setup.sql
-- Create profiles table
CREATE TABLE profiles (
  id UUID REFERENCES auth.users ON DELETE CASCADE,
  email TEXT,
  credits INTEGER DEFAULT 300,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::text, NOW()) NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::text, NOW()) NOT NULL,
  PRIMARY KEY (id)
);

-- Create user_mails table
CREATE TABLE user_mails (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES profiles(id) ON DELETE CASCADE,
  recipient_email TEXT NOT NULL,
  subject TEXT NOT NULL,
  content TEXT NOT NULL,
  mail_type TEXT NOT NULL CHECK (mail_type IN ('custom', 'template')),
  credits_used INTEGER NOT NULL,
  sent_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::text, NOW()) NOT NULL
);

-- Enable Row Level Security
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE user_mails ENABLE ROW LEVEL SECURITY;

-- Create policies
CREATE POLICY "Users can view own profile" ON profiles FOR SELECT USING (auth.uid() = id);
CREATE POLICY "Users can update own profile" ON profiles FOR UPDATE USING (auth.uid() = id);
CREATE POLICY "Users can view own mails" ON user_mails FOR SELECT USING (auth.uid() = user_id);
CREATE POLICY "Users can insert own mails" ON user_mails FOR INSERT WITH CHECK (auth.uid() = user_id);

Running the Development Server

Step 5: Start the Development Server

npm run dev

Open http://localhost:3000 in your browser to see Mail Assist running!

Success!
If you see the Mail Assist homepage, you've successfully set up the development environment. You can now sign up for an account and start sending emails.

Verification Steps

To ensure everything is working correctly:

  1. Authentication - Try signing up with a new account
  2. Database - Check if your profile is created in Supabase
  3. Email Sending - Send a test email (use sandbox domain if not verified)
  4. Credits - Verify that credits are deducted after sending

Troubleshooting

Common Issues

Build Errors
If you encounter TypeScript errors, ensure all environment variables are properly set and restart the development server.
Database Connection
If database operations fail, verify your Supabase URL and keys are correct, and that RLS policies are properly configured.
Email Sending Issues
If emails aren't sending, check your Resend API key and ensure your domain is verified (or use the sandbox domain for testing).

Next Steps

Now that you have Mail Assist running locally, explore these sections: