brev-ly

brev-ly is a modern and efficient URL shortener developed with a full-stack architecture. It features a monorepo structure containing a Node.js backend and a React frontend.

Key Features

• URL Shortening: Create short links with random or custom slugs.
• Analytics: Track visits to shortened links.
• Image Upload: Upload images for custom links (integrated with Cloudflare R2).
• Management: List, manage, and delete links.
• Export: Export link data to CSV.
• API Documentation: RESTful API documented with Swagger.

Architecture

The project is organized as a monorepo:

• server/: Backend API (Node.js/Fastify)
• web/: Frontend Interface (React/Vite)

Technology Stack

Backend (/server)

• Runtime & Framework:

  • Node.js
  • Fastify v5.6.0
  • TypeScript v5.9.2

• Database & ORM:

  • PostgreSQL
  • Drizzle ORM v0.44.5
  • Drizzle Kit v0.31.5

• Validation & Documentation:

  • Zod v4.1.11
  • Fastify Swagger v9.5.2

• Storage & Infrastructure:

  • AWS SDK S3 v3.899.0 (Cloudflare R2 integration)
  • Docker

• Tooling:

  • TSX
  • TSup
  • Biome

Frontend (/web)

• Core:

  • React v19.1.1
  • Vite v7.1.7
  • TypeScript v5.8.3

• Routing & State:

  • TanStack Router v1.132.47
  • TanStack Query v5.90.2

• Styling:

  • Tailwind CSS v4.1.13
  • Tailwind Variants

• UI Components & Utils:

  • React Hook Form
  • React Toastify
  • Phosphor Icons

Package Management

• pnpm v10.12.1

Setup and Execution Guide

Prerequisites

• Node.js >= 18.x
• pnpm >= 10.x
• Docker & Docker Compose

1. Backend Setup (/server)

cd server
pnpm install

# Configure Environment
cp .env.example .env
# Edit .env with your credentials

# Start Database
docker-compose up -d db

# Run Migrations
pnpm db:generate
pnpm db:migrate

# Start Dev Server
pnpm dev

Server runs at http://localhost:3333. Swagger docs at /docs.

2. Frontend Setup (/web)

cd web
pnpm install

# Configure Environment
cp .env.example .env

# Start Dev Server
pnpm dev

Frontend runs at http://localhost:5173.

3. Docker Execution (Full Stack)

To run the backend and database entirely in Docker:

cd server
docker-compose up -d

Available Scripts

Backend

• pnpm dev: Development mode
• pnpm build: Build for production
• pnpm start: Start production build
• pnpm db:studio: Open Drizzle Studio

Frontend

• pnpm dev: Development server
• pnpm build: Production build
• pnpm preview: Preview production build
• pnpm lint: Run ESLint