Skip to content
ggauravkyPublic

About

A modern full-stack social media platform built with Next.js 16, React 19, Prisma, PostgreSQL, Clerk Auth, and UploadThing. Features posts, likes, comments, follows, notifications, profiles, and real-time social interactions.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

InstaX Banner

A premium, lightning-fast social media platform designed for visual and interactive excellence.

Explore the Live App Β»

Next.js React TypeScript Tailwind CSS Prisma PostgreSQL Clerk Vercel License


πŸ“– Table of Contents

  1. About InstaX
  2. Key Features
  3. Architecture
  4. Tech Stack
  5. Performance Optimizations
  6. Getting Started
  7. Environment Variables
  8. Project Structure
  9. Roadmap
  10. Contributing
  11. Author

🌟 About InstaX

InstaX is a cutting-edge social media platform designed to deliver a modern, clutter-free user experience. Built with performance and visuals in mind, it provides a seamless space for posting, sharing media, following creators, liking posts, commenting, and tracking notifications.

Why it exists

Many social media clones are plagued with sluggish response times, database bottlenecks, unoptimized images causing layout shifts, and slow client-side waterfall fetches. InstaX solves these issues by combining Next.js 16's server architecture and React 19's concurrent features with lightweight server queries, ensuring pages load and update instantly.

Who it is built for

  • Recruiters & Engineering Managers looking for a production-grade demonstration of a Next.js 16 full-stack App Router codebase utilizing Server Actions, Prisma optimization, and responsive design.
  • Developers seeking a modern template with clean separation of client-server boundaries, optimized image handling, and reliable third-party integrations (Clerk, UploadThing, Neon).

🎨 Key Features

Feature Description
πŸ”’ Advanced Authentication Fully managed user lifecycle through Clerk Auth with secure signup, login, and Google OAuth integrations.
πŸ“‚ Media Uploads Instant, high-speed image uploads up to 4MB backed by UploadThing's edge CDN.
πŸ“ Post Creation Drag-and-drop image sharing coupled with text posts. Supports post deletion for owners.
πŸ’¬ Comments & Likes Write thoughts on posts and toggle likes instantly with optimistic client updates.
πŸ‘₯ Social Connections Dynamic follow/unfollow system with automatic counters on profile cards.
πŸ‘€ Profile Customization Update username (validated in real-time), edit display name, biography, website, and location.
πŸ”” Notification Hub Real-time notifications for likes, comments, and new followers, complete with instant server-side read status.
πŸŒ“ Dark Mode Full system-based and toggleable theme settings with glassmorphic layouts.

πŸ—οΈ Architecture

The application is structured around a server-first, edge-optimized routing pipeline. Here is how components communicate:

graph TD
    classDef client fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#fff;
    classDef api fill:#1e293b,stroke:#a855f7,stroke-width:2px,color:#fff;
    classDef db fill:#020617,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef auth fill:#111827,stroke:#6366f1,stroke-width:2px,color:#fff;
    classDef storage fill:#0b0f19,stroke:#f97316,stroke-width:2px,color:#fff;

    Client["πŸ’» Client (Next.js Client Components)"]:::client
    ServerActions["⚑ Server Actions & API (Next.js 16)"]:::api
    Database["πŸ—„οΈ Database (Neon Serverless PostgreSQL)"]:::db
    Prisma["Prisma ORM (Client v6)"]:::db
    Clerk["πŸ”’ Authentication (Clerk Auth)"]:::auth
    UploadThing["πŸ“ Storage CDN (UploadThing)"]:::storage

    Client -- "1. Authenticates Session" --> Clerk
    Client -- "2. Uploads Media Files" --> UploadThing
    Client -- "3. Invokes Mutations & Queries" --> ServerActions
    ServerActions -- "4. Reads Auth Context" --> Clerk
    ServerActions -- "5. Database Queries" --> Prisma
    Prisma -- "6. Maps Schemas" --> Database
    UploadThing -- "7. Returns Media CDN Links" --> Client
Loading

πŸ’» Tech Stack

Frontend

  • Framework: Next.js 16.2.6 (App Router, dynamic routing)
  • Library: React 19.2.4 (React Server Components, Concurrent Features)
  • Language: TypeScript
  • Styling: Tailwind CSS v4.0 & Radix UI

Backend & Database

  • API Architecture: Next.js Server Actions (type-safe RPC endpoints)
  • Database ORM: Prisma Client v6.19.3
  • Database Engine: Neon Serverless PostgreSQL

Services & Infrastructure

  • Authentication: Clerk Core API (Session management & OAuth sync)
  • File Storage: UploadThing (Edge CDN integration)
  • Hosting Platform: Vercel

πŸš€ Performance Optimizations

InstaX is heavily optimized for fast load times and a lag-free feel:

  • βš›οΈ Optimistic Updates: Like-toggling updates UI counters instantly on the client before the server database confirmation finishes.
  • ⚑ No Client Waterfalls: The /notifications and user /profile views are server-rendered (SSR), delivering complete markup to the client in a single request.
  • πŸ–ΌοΈ Image Optimization & Aspect Ratios: Users' avatars are optimized through Clerk's image API using next/image with responsive sizes. Post images maintain native aspect ratios (preventing layout shift) and utilize edge lazy loading.
  • πŸ—„οΈ Prisma Database Indexes:
    • @@index([authorId, createdAt]) speeds up user-profile feed pagination.
    • @@index([createdAt]) speeds up global home feed sorting.
    • @@index([userId, postId]) speeds up double-like prevention checks.
  • 🎯 Parallel Data Fetching: Operations like toggleLike fetch target posts and verify status in parallel using Promise.all() to minimize DB wait times.

βš™οΈ Getting Started

Prerequisites

Make sure you have Node.js installed (v18.x or later recommended).

1. Clone the repository

git clone https://github.com/ggauravky/InstaX.git
cd InstaX

2. Install dependencies

npm install

3. Setup environment variables

Copy the .env.example file and fill in your keys:

cp .env.example .env

(Refer to the Environment Variables section below to retrieve these values).

4. Setup Prisma & Database schema

Sync the Prisma schema with your database (this creates indexes and tables):

npx prisma db push

5. Launch the development server

npm run dev

Open http://localhost:3000 in your browser to view the application.


πŸ”‘ Environment Variables

To run this project, you will need to add the following variables to your .env file:

Variable Description Required Source
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY Public publishable key for Clerk client Yes Clerk Dashboard
CLERK_SECRET_KEY Private secret key for Clerk backend Yes Clerk Dashboard
DATABASE_URL Connection URI string for PostgreSQL database Yes Neon Dashboard
UPLOADTHING_TOKEN API Token for uploading files to UploadThing Yes UploadThing Dashboard

πŸ“ Project Structure

InstaX/
β”œβ”€β”€ prisma/
β”‚   β”œβ”€β”€ schema.prisma      # Prisma schema models & indexes
β”œβ”€β”€ public/
β”‚   β”œβ”€β”€ avatar.png         # Default fallback avatar
β”‚   β”œβ”€β”€ banner.svg         # README branding banner
β”‚   β”œβ”€β”€ logo.svg           # Main SVG logo
β”‚   └── social-preview.svg # OpenGraph preview banner
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ actions/           # Next.js Server Actions
β”‚   β”‚   β”œβ”€β”€ notification.action.ts
β”‚   β”‚   β”œβ”€β”€ post.action.ts
β”‚   β”‚   β”œβ”€β”€ profile.action.ts
β”‚   β”‚   └── user.action.ts
β”‚   β”œβ”€β”€ app/               # App Router Pages & API routes
β”‚   β”‚   β”œβ”€β”€ api/           # API routes (uploadthing endpoints)
β”‚   β”‚   β”œβ”€β”€ notifications/ # Notifications SSR page & Client logic
β”‚   β”‚   β”œβ”€β”€ profile/       # Profile management and username routes
β”‚   β”‚   β”œβ”€β”€ layout.tsx
β”‚   β”‚   └── page.tsx       # Home Feed Page
β”‚   β”œβ”€β”€ components/        # Shared UI and Layout components
β”‚   β”‚   β”œβ”€β”€ ui/            # Radix / shadcn core elements
β”‚   β”‚   β”œβ”€β”€ CreatePost.tsx
β”‚   β”‚   β”œβ”€β”€ PostCard.tsx
β”‚   β”‚   β”œβ”€β”€ WhoToFollow.tsx
β”‚   β”‚   └── sidebar.tsx
β”‚   β”œβ”€β”€ hooks/             # Custom React Hooks
β”‚   β”œβ”€β”€ lib/               # Shared libraries (prisma client, utils)
β”‚   └── tsconfig.json      # TypeScript configurations

πŸ—ΊοΈ Roadmap

  • Clerk Auth Integration (Google OAuth + Form Auth)
  • UploadThing CDN Storage (Image uploads up to 4MB)
  • Likes & Comments system (With optimistic UI rendering)
  • Prisma PostgreSQL Indexes (Speeding up queries & feeds)
  • Username edit updates (Real-time debounce validator)
  • Vercel Production Build optimizations (SSR & dynamic page compiling)
  • Direct Private Messaging (Real-time chat channels)
  • Post Search & Hashtags (Searching feed by tags or names)
  • Rich Text posts (Markdown formatting within posts)

🀝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

πŸ‘€ Author

InstaX Logo

Gaurav Kumar Yadav

Full-Stack Web Developer & Open Source Maintainer

Portfolio Website β€’ GitHub β€’ LinkedIn β€’ Email Me


Built with ❀️ using Next.js, React, Tailwind CSS, Prisma, Neon, and Clerk. Distributed under the MIT License.

About

A modern full-stack social media platform built with Next.js 16, React 19, Prisma, PostgreSQL, Clerk Auth, and UploadThing. Features posts, likes, comments, follows, notifications, profiles, and real-time social interactions.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages