Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
367 lines (285 loc) · 10.3 KB

SETUP_GUIDE.md

File metadata and controls

367 lines (285 loc) · 10.3 KB

Uplink - Quick Start Guide

Overview

You now have a complete, production-ready URL shortener application built with:

  • Next.js 15 - App Router, TypeScript
  • Supabase - PostgreSQL Database + Authentication
  • Tailwind CSS - Responsive design
  • shadcn/ui - Beautiful UI components
  • Analytics - Click tracking and statistics

The application is fully built and ready for deployment!

Project Location

/home/arnav/Code/uplink/

Quick Start (Local Development)

1. Create Supabase Project

  1. Go to https://supabase.com and sign up (free tier available)
  2. Create a new project
  3. Wait for initialization (5-10 minutes)

2. Setup Database Schema

  1. In Supabase dashboard, go to SQL Editor → New Query
  2. Copy-paste the entire contents of /home/arnav/Code/uplink/sql-schema.sql
  3. Click Run
  4. Verify tables were created (check Table Editor)

3. Get Supabase Credentials

  1. Go to Settings → API
  2. Copy:
    • Project URL (NEXT_PUBLIC_SUPABASE_URL)
    • anon public key (NEXT_PUBLIC_SUPABASE_ANON_KEY)

4. Setup Environment Variables

cd /home/arnav/Code/uplink
cp .env.local.example .env.local

Edit .env.local with your Supabase credentials:

NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJxx...
NEXT_PUBLIC_SHORT_URL_BASE=http://localhost:3000
NEXT_PUBLIC_SHORT_URL_DOMAINS=localhost:3000

5. Run Development Server

cd /home/arnav/Code/uplink
npm run dev

Open http://localhost:3000 in your browser!

Features You Can Test Locally

✅ Sign Up - Create a new account ✅ Sign In - Log in to your account
✅ Create Links - Shorten URLs with auto-generated or custom slugs ✅ View Dashboard - See all your shortened links ✅ Click Links - Each click increments the counter ✅ Analytics - View click statistics for each link ✅ Delete Links - Remove links you don't need anymore ✅ Copy to Clipboard - Quick copy of short URLs

Deployment to Vercel

Step 1: Prepare GitHub Repository

cd /home/arnav/Code/uplink

# Initialize git (if not already done)
git init
git add .
git commit -m "Initial commit: URL shortener with Supabase"

# Push to GitHub
git remote add origin https://github.com/YOUR_USERNAME/uplink.git
git branch -M main
git push -u origin main

Step 2: Deploy on Vercel

  1. Go to https://vercel.com/dashboard
  2. Click Add New → Project
  3. Select your GitHub repository
  4. Click Import
  5. Add Environment Variables:
  6. Click Deploy

Your app will be live in ~2-3 minutes!

Step 3: Custom Domains (Optional but Recommended)

Add your custom domains to Vercel:

For uplink.neopanda.tech:

  1. Go to Vercel project Settings → Domains
  2. Click Add and enter uplink.neopanda.tech
  3. Follow Vercel's DNS setup instructions
  4. Update your domain's DNS records accordingly

For meetra.live:

  1. Repeat the process with meetra.live

Step 4: Update Environment Variables for Production

Once custom domains are set up, update Vercel environment variables:

NEXT_PUBLIC_SHORT_URL_BASE=https://uplink.neopanda.tech
NEXT_PUBLIC_SHORT_URL_DOMAINS=uplink.neopanda.tech,meetra.live,your-vercel-app.vercel.app

Project Structure Overview

uplink/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # Root layout with Sonner provider
│   ├── page.tsx                 # Beautiful landing page
│   ├── (auth)/                  # Auth route group
│   │   ├── login/page.tsx       # Login page
│   │   └── signup/page.tsx      # Signup page
│   ├── (dashboard)/             # Protected dashboard routes
│   │   ├── dashboard/page.tsx   # Main dashboard
│   │   └── links/[id]/page.tsx  # Link analytics page
│   ├── api/
│   │   ├── links/route.ts       # Create & list links
│   │   ├── links/[id]/route.ts  # Delete & detail
│   │   └── redirect/[code]/route.ts # Tracking endpoint
│   └── [code]/page.tsx          # Catch-all redirect page
│
├── components/
│   ├── Navigation.tsx           # Top nav with auth
│   ├── auth/
│   │   ├── LoginForm.tsx
│   │   └── SignupForm.tsx
│   ├── dashboard/
│   │   ├── CreateLinkForm.tsx   # Form to create links
│   │   ├── LinkCard.tsx         # Individual link card
│   │   └── LinkList.tsx         # List of user's links
│   └── ui/                      # shadcn/ui components
│
├── lib/
│   ├── supabase/
│   │   ├── client.ts            # Browser Supabase client
│   │   ├── server.ts            # Server Supabase client
│   │   └── types.ts             # TypeScript types
│   ├── urlShortener.ts          # Link generation logic
│   └── utils.ts                 # Utility functions
│
├── middleware.ts                # Auth middleware
├── sql-schema.sql              # Database schema (for setup)
├── .env.local.example          # Environment template
└── README.md                   # Full documentation

Database Schema

short_urls Table

Field Type Purpose
id UUID Primary key
user_id UUID Link owner
original_url TEXT The long URL
short_code VARCHAR(10) The short code
custom_slug VARCHAR(50) Optional custom slug
is_permanent BOOLEAN Permanent or temporary
expires_at TIMESTAMP Expiration date (null = permanent)
click_count INT Total clicks
created_at TIMESTAMP Creation time
updated_at TIMESTAMP Last update

url_clicks Table

Field Type Purpose
id UUID Primary key
short_url_id UUID Link reference
clicked_at TIMESTAMP When clicked
referrer TEXT HTTP referrer
user_agent TEXT Browser info

API Endpoints

Authentication (Supabase)

  • POST /api/auth/[...auth] - Auto-handled by Supabase

Links Management

  • POST /api/links - Create new shortened URL
  • GET /api/links - Get user's links
  • GET /api/links/[id] - Get link details with analytics
  • DELETE /api/links/[id] - Delete a link

Redirect & Analytics

  • GET /api/redirect/[code] - Redirect and track click
  • GET /[code] - Catch-all page redirect

Key Features

1. URL Shortening

  • Auto-generated 8-character base62 codes (0-9, a-z, A-Z)
  • Optional custom slugs (2-50 characters)
  • Unique constraint prevents duplicates

2. Link Expiration

  • Default: 30-day temporary links
  • Optional: Make links permanent (no expiration)
  • Automatic checks for expired links

3. Analytics & Tracking

  • Click counter for each link
  • Recent clicks with referrer & user agent info
  • Analytics page with statistics
  • Real-time updates

4. Security

  • Row Level Security (RLS) - Users only see their own links
  • Server-side authentication checks
  • Environment variables for secrets
  • Secure password hashing (Supabase)

Troubleshooting

"Unauthorized" Error

  • Check that you're logged in
  • Clear browser cookies
  • Try signing up again

Links Not Creating

  • Verify Supabase credentials in .env.local
  • Check database connection in Supabase dashboard
  • Look at browser console for error messages

Redirects Not Working

  • Ensure short_code exists in database
  • Check if link is expired (30 days by default)
  • Verify the original URL is valid

Custom Domain Not Working

  • Wait 24-48 hours for DNS propagation
  • Verify DNS records in domain registrar
  • Check Vercel domain settings

Useful Commands

# Development
npm run dev          # Start dev server on http://localhost:3000

# Production
npm run build        # Build for production
npm run start        # Start production server

# Database
npm run db:push     # Sync schema with Supabase (if using migrations)

# Linting
npm run lint        # Run TypeScript and ESLint checks

Next Steps

  1. Test Locally (3-5 minutes)

    • Create account and shorten a test URL
    • Click the short link and verify analytics

  2. Deploy to Vercel (5 minutes)

    • Push to GitHub
    • Import in Vercel
    • Add environment variables

  3. Setup Custom Domains (30 minutes)

    • Add domains in Vercel
    • Update DNS records
    • Test with your custom domain

Common Customizations

Change Default Expiration (from 30 days)

Edit lib/urlShortener.ts:

export function calculateExpiration(isPermanent: boolean): string | null {
  if (isPermanent) return null;
  const date = new Date();
  date.setDate(date.getDate() + 90); // Change 30 to 90
  return date.toISOString();
}

Modify Short Code Length

Edit components/dashboard/CreateLinkForm.tsx:

// Line where generateShortCode is called
const code = generateShortCode(10); // Change 8 to 10

Change Theme Colors

Edit app/globals.css CSS variables or tailwind.config.ts

Add More Authentication Methods

Supabase supports: Google, GitHub, Discord, etc.

Performance Tips

  • Database indexes are already optimized
  • Image optimization via Next.js Image component
  • CSS is minified with Tailwind
  • API routes are optimized for Vercel

Security Best Practices

✅ Row Level Security enabled ✅ Environment variables protected ✅ HTTPS enforced on Vercel ✅ SQL injection protected (via Supabase client) ✅ XSS protection via React ✅ CSRF tokens auto-handled by Next.js

Support & Resources

What's Included

✅ Complete source code ✅ Database schema (SQL) ✅ Environment setup guide ✅ API documentation ✅ Component examples ✅ Error handling ✅ TypeScript support ✅ Responsive design ✅ Analytics dashboard ✅ Production-ready

File Sizes

  • Total dependencies: ~200MB (node_modules)
  • Source code: ~150KB
  • Build output: ~2MB (after Vercel optimization)

Your Uplink URL Shortener is ready to go! 🚀

Start with local development, then deploy to Vercel with your custom domains!