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.
• Management: List, manage, and delete links.
• Export: Export link data to CSV using database cursors for memory-efficient processing, with the API streaming the output directly to Cloudflare R2.
• 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 | TypeScript

• Database & ORM:

  • PostgreSQL | Drizzle ORM | Drizzle Kit

• Validation & Documentation:

  • Zod | Fastify Swagger

• Storage & Infrastructure:

  • AWS SDK S3 (Cloudflare R2 integration) | Docker

• Tooling:

  • TSX | TSup | Biome

Frontend (/web)

• Core:

  • React | Vite | TypeScript

• Routing & State:

  • TanStack Router | TanStack Query

• Styling:

  • Tailwind CSS | Tailwind Variants

• UI Components & Utils:

  • React Hook Form | React Toastify | Phosphor Icons

Package Management

• pnpm

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:

# update the credentials in docker-compose.yml file
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