- About InstaX
- Key Features
- Architecture
- Tech Stack
- Performance Optimizations
- Getting Started
- Environment Variables
- Project Structure
- Roadmap
- Contributing
- Author
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.
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.
- 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).
| 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. |
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
- 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
- API Architecture: Next.js Server Actions (type-safe RPC endpoints)
- Database ORM: Prisma Client v6.19.3
- Database Engine: Neon Serverless PostgreSQL
- Authentication: Clerk Core API (Session management & OAuth sync)
- File Storage: UploadThing (Edge CDN integration)
- Hosting Platform: Vercel
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
/notificationsand user/profileviews 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
toggleLikefetch target posts and verify status in parallel usingPromise.all()to minimize DB wait times.
Make sure you have Node.js installed (v18.x or later recommended).
git clone https://github.com/ggauravky/InstaX.git
cd InstaXnpm installCopy the .env.example file and fill in your keys:
cp .env.example .env(Refer to the Environment Variables section below to retrieve these values).
Sync the Prisma schema with your database (this creates indexes and tables):
npx prisma db pushnpm run devOpen http://localhost:3000 in your browser to view the application.
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 |
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
- 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)
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Full-Stack Web Developer & Open Source Maintainer
Portfolio Website β’ GitHub β’ LinkedIn β’ Email Me