Meadows - A Next.js Social Media for Gen-Z 🍃

A full-featured social feed application built with Next.js, Supabase, and React Query. Meadows lets users create posts (with optional images), follow other users, like posts, and manage their profiles. It includes infinite scrolling, light/dark mode, and a responsive, mobile-friendly design.

Important

Live Web App: https://meadows.vercel.app/. 🍃

Please give it a try and start sharing your thoughts stylishly!

---

Table of Contents

1. Features
2. Tech Stack
3. Getting Started
4. Environment Variables
5. Project Structure
6. Architecture Docs
7. Key Components
8. Scripts
9. Supabase Setup
10. Testing & Formatting
11. GitHub Actions
12. Contributing
13. License
14. Acknowledgments
15. Contact

---

User Interface

---

Features

• User Authentication via Supabase
• Profile Management: upload/change avatar, view followers/following
• Post Creation: text + multiple image uploads with responsive galleries
• Infinite Scrolling for feeds and profiles
• Like/Unlike posts
• Vibe Check Reactions: one-tap social signals (Aura Up, Real, Mood, Chaotic) with a live top-vibe meter
• Daily Vibe Pulse: one-tap daily check-in + live social mood dashboard with a Vibe Mix Wheel, Vibe Skyline, and weekly recap
• Quick Poll Posts: create 2-4 option polls in the composer, vote directly in feed or post detail, and see live percentages
• Comments & Replies: full post threads with one-level reply depth for clean conversation UX
• Comment Vibe Reactions: same vibe language on comments for consistent emotional feedback
• Mentions in Comments: @handle suggestions while typing, mention highlighting, and mention notifications
• Notifications Center: in-header unread badge and latest interaction notifications
• Global Profile Search: live typeahead search by name/handle, keyboard navigation, click-to-open profile
• Follow/Unfollow other users
• Light/Dark Mode toggle
• Share & Copy Link buttons using Web Share API
• Responsive Layout with mobile-optimized navigation and interaction controls
• Client-side Bookmarking (via localStorage)
• Server-Side Rendering for initial data fetch
• TypeScript for type safety
• Zod for schema validation
• ESLint & Prettier for code quality
• and more!

---

Tech Stack

• Framework: Next.js
• Authentication & Database: Supabase
• Data Fetching: React Query
• UI Components: Custom, plus lucide-react icons
• Styling: Tailwind CSS (via shadcn/ui conventions)
• File Storage: Supabase Storage
• and more!

---

Getting Started

1. Clone the repo

git clone https://github.com/hoangsonww/Meadows-Social-Media.git
cd Meadows-Social-Media/web

2. Install dependencies

npm install
# or
yarn

3. Set up environment variables (see next section)

4. Run the dev server

npm run dev
# or
yarn dev

Open http://localhost:3000 in your browser.

---

Environment Variables

Create a .env.local file at project root with:

NEXT_PUBLIC_SUPABASE_URL=<your_supabase_url>
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your_supabase_anon_key>

You can find these in your Supabase project settings.

---

Project Structure

/
├── database/                         # SQL schema/feature files
├── migrations/                       # runnable migration scripts
├── web/
│   ├── components/
│   │   ├── header.tsx               # global navbar + notifications + profile search
│   │   ├── post.tsx                 # feed post card
│   │   ├── post-comments.tsx        # comments, replies, mentions, comment vibes
│   │   ├── daily-vibe-pulse.tsx     # pulse dashboard + vibe charts
│   │   └── ui/                      # shadcn/ui-style components
│   ├── pages/
│   │   ├── index.tsx                # landing page
│   │   ├── home.tsx                 # main feed + composer
│   │   ├── pulse.tsx                # daily pulse page
│   │   ├── post/[id].tsx            # post detail + comments
│   │   ├── profile/[id].tsx         # profile page
│   │   ├── login.tsx / signup.tsx   # auth entry
│   │   └── _app.tsx
│   ├── utils/supabase/
│   │   ├── clients/                 # browser + SSR clients
│   │   ├── models/                  # Zod schemas
│   │   └── queries/                 # data access logic
│   ├── styles/globals.css
│   └── package.json
└── README.md

---

Architecture Docs

For a full technical deep-dive (runtime boundaries, data model, query architecture, feature flows, and Mermaid diagrams), see:

• ARCHITECTURE.md

---

Key Components

<Header />

• Responsive global navbar (mobile-first behavior)
• Live profile search by name/@handle with keyboard navigation
• Notifications dropdown with unread badge and read-on-open behavior
• Quick access actions: Pulse, Create Post, Theme toggle, Account menu

<HomePage />

• “Write a Post” card with multi-image upload and optional polls
• Tabs: Feed / Following / Liked / Mine
• Inline infinite scroll of <PostCard />

<PostFeed /> (embedded directly)

• Renders <PostCard /> components inline
• IntersectionObserver to fetch more

<PostPage />

• Single post view
• Share, copy link, email, print, bookmark button
• Full comments experience via <PostComments />

<PostComments />

• Top/Newest comment sorting
• One-level threaded replies (reply-to-reply handled cleanly in the same thread model)
• Mention suggestions and highlighted mentions
• Comment vibe reactions, report, and delete-own-comment actions

<DailyVibePulse />

• Daily vibe check-in with optional status note
• Meadows Pulse visualization (Vibe Mix Wheel + Vibe Skyline)
• Circle vibe statuses and weekly recap cards
• Top posts influencing today’s social mood

<PublicProfilePage />

• Profile header: avatar, name, handle, follow button
• Stats: posts, followers, following
• Infinite scroll of user’s posts
• Modals for followers/following lists

---

Scripts

• dev: Start development server
• build: Create a production build
• start: Run production build
• lint: Run ESLint
• format: Run Prettier

---

Supabase Setup

This project uses Supabase for Auth, Postgres, and Storage.

To set up Supabase:

1. Create a new project on Supabase.
2. Set up auth provider(s) (email/password is enough for local development).
3. Run SQL from the migration files in /migrations, especially:
   • all_tables_only.sql for full table definitions
   • 20260316_add_daily_vibe_and_comments.sql for Daily Vibe Pulse + comments/replies + notifications feature pack
4. Create/verify storage buckets:
   • avatars
   • images
5. Update .env.local with NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY.
6. Verify app flows: auth, post creation, vibe reactions, comments/replies, pulse dashboard, and profile search.

FYI, you can find the schema definitions under the database directory. Below is a visual representation of the database schema:

---

Testing & Formatting

This project uses Jest for testing and Prettier for code formatting.

To run tests:

cd web

npm run test
# or
yarn test

# To run tests in watch mode
npm run test:watch
# or
yarn test:watch

# To run tests with coverage report
npm run coverage
# or
yarn coverage

To format code:

cd web

npm run format
# or
yarn format

Running npm run format will automatically format your code according to the Prettier configuration. It is recommended to run this command every time before committing changes to ensure consistent code style.

---

GitHub Actions

This project uses GitHub Actions for continuous integration. The workflow is defined in .github/workflows/ci.yml. It runs the following checks on every push and pull request:

• Linting with ESLint
• Formatting with Prettier
• Running tests with Jest
• Building the Next.js application
• Checking for type errors with TypeScript
• Deploying to Vercel if all checks pass

The workflow ensures that all code changes meet the project's quality standards before being merged into the main branch.

---

Contributing

1. Fork this repo
2. Create a feature branch (git checkout -b feature/x)
3. Commit your changes (git commit -m "feat: your message")
4. Push to your branch (git push origin feature/x)
5. Open a pull request

Please ensure all new code is covered by tests and adheres to the project’s coding standards.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

Please note that while this project is open-source, it is intended for educational purposes and personal use. Please do not use it for commercial purposes without prior permission, and always give credit to the original authors regardless of usage.

---

Acknowledgments

Big thanks to Prof. Ajay Gandecha at UNC-Chapel Hill for the inspiration and basic structure of this project. The original project was a simple social media app, and this version has been significantly expanded with additional features and improvements.

Additionally, thanks to the open-source community for the libraries and tools that made this project possible, including Next.js, Supabase, React Query, Tailwind CSS, and many others.

---

Contact

If you have any questions or feedback, feel free to reach out to me via either:

• Email: hoangson091104@gmail.com
• GitHub: hoangsonww
• LinkedIn: Son Nguyen

I welcome contributions, suggestions, and any issues you may encounter while using this project. Your feedback is invaluable in making Meadows better for everyone!

---

Thank you for checking out Meadows! I hope you find it useful and enjoyable to use. If you have any questions or suggestions, feel free to reach out or open an issue on GitHub. Happy coding! 🍃