Next.js Social Media Platform Development Guide

This skill provides comprehensive guidance for developing a modern social media platform similar to Twitter, featuring posts, hashtags, AI agent interactions, and real-time social features using Next.js 15 and modern web technologies.

Project Architecture

Core Technology Stack

Essential Development Commands

```bash

npm run dev # Start development server with Turbopack

npm run build # Build production application

npm run lint # Run ESLint for code quality

npm run db:generate # Generate Drizzle database migrations

npm run db:migrate # Run database migrations

npm run db:push # Push schema changes to database

npm run db:studio # Open Drizzle Studio for database management

```

Database Schema Design

Core Entities

**Posts Table**

**Hashtags System**

**AI Agents**

**Attachments**

Database Configuration

```typescript

// drizzle.config.ts example structure

export default {

schema: "./lib/db/schema.ts",

out: "./drizzle",

driver: "pg",

dbCredentials: {

connectionString: process.env.DATABASE_URL,

},

}

```

Directory Structure

```

app/

├── api/ # Backend API endpoints

├── post/[id]/ # Individual post pages

├── hashtag/[name]/ # Hashtag-specific pages

└── agents/ # Agent management pages

components/

├── ui/ # shadcn/ui components

├── providers/ # Context providers

├── Timeline/ # Timeline components

└── PostCard/ # Post display components

lib/

├── db/ # Database schema and queries

├── utils.ts # Utility functions

└── validations/ # Zod schemas

hooks/ # Custom React hooks

```

Key Implementation Patterns

Component Development

```typescript

// Use cn() utility for conditional styling

import { cn } from "@/lib/utils"

// Implement proper TypeScript types

interface PostCardProps {

post: Post

className?: string

}

// Follow shadcn/ui patterns

export function PostCard({ post, className }: PostCardProps) {

return (

<div className={cn("border rounded-lg p-4", className)}>

{/* Component content */}

</div>

)

}

```

Database Queries with Drizzle

```typescript

// Use Drizzle ORM for type-safe database operations

import { db } from "@/lib/db"

import { posts, hashtags } from "@/lib/db/schema"

// Example query with joins

const postsWithHashtags = await db

.select()

.from(posts)

.leftJoin(postHashtags, eq(posts.id, postHashtags.postId))

.leftJoin(hashtags, eq(postHashtags.hashtagId, hashtags.id))

```

Form Handling

```typescript

// Use React Hook Form with Zod validation

import { useForm } from "react-hook-form"

import { zodResolver } from "@hookform/resolvers/zod"

import { z } from "zod"

const postSchema = z.object({

content: z.string().min(1).max(280),

})

export function CreatePostForm() {

const form = useForm({

resolver: zodResolver(postSchema),

})

// Form implementation

}

```

Feature Implementation Guide

Social Timeline Features

1. **Post Creation**

- Character limit (280 characters)

- Hashtag detection and linking

- Image/media attachment support

- Draft saving capabilities

2. **Post Threading**

- Reply functionality using `parentId`

- Thread visualization

- Conversation tracking

3. **Hashtag System**

- Automatic hashtag extraction from post content

- Trending hashtag calculation

- Hashtag-specific feeds

AI Agent Integration

1. **Agent Configuration**

- Agent personality setup

- Response trigger configuration

- Mention detection system

2. **Agent Interactions**

- Automatic response generation

- Context-aware conversations

- Agent mention tracking

Real-time Features

1. **TanStack Query Integration**

- Optimistic updates for posts

- Real-time data synchronization

- Efficient caching strategies

2. **Live Updates**

- New post notifications

- Real-time comment updates

- Live hashtag trending

Styling and UI Guidelines

Tailwind CSS Patterns

```css

/* Use CSS variables for theming */

:root {

--background: 0 0% 100%;

--foreground: 222.2 84% 4.9%;

--primary: 221.2 83.2% 53.3%;

}

/* Component styling example */

.post-card {

@apply border border-border rounded-lg p-4 bg-card text-card-foreground;

}

```

Component Variants

```typescript

// Use Class Variance Authority (CVA) for variants

import { cva } from "class-variance-authority"

const buttonVariants = cva(

"inline-flex items-center justify-center rounded-md text-sm font-medium",

{

variants: {

variant: {

default: "bg-primary text-primary-foreground hover:bg-primary/90",

destructive: "bg-destructive text-destructive-foreground",

},

size: {

default: "h-10 px-4 py-2",

sm: "h-9 rounded-md px-3",

},

},

}

)

```

Development Best Practices

Server Management

Testing Strategy

Code Quality

Performance Optimization

Environment Configuration

```bash

Required environment variables

DATABASE_URL=postgresql://...

NEXT_PUBLIC_APP_URL=http://localhost:3000

Optional API keys for AI agents

OPENAI_API_KEY=...

ANTHROPIC_API_KEY=...

```

This skill provides a complete foundation for building modern social media platforms with advanced features like AI agent interactions, real-time updates, and comprehensive social functionality using the latest web development technologies.