nextjs-saas-template/README.md

Zero-config SaaS starter kit for AI-assisted development. Pre-configured Next.js 15 + Supabase + Tailwind CSS with authentication, dashboard, and Vercel deployment ready. Perfect for Cursor AI, ChatGPT, Claude, Grok, and other LLMs to work with immediatel

# Next.js SaaS Template - AI-Ready Starter Kit

Zero-config SaaS starter kit designed for AI-assisted development. Pre-configured with Next.js 15, Supabase, and Tailwind CSS - ready for Cursor AI, ChatGPT, Claude, Grok, and other LLMs to work with immediately. No setup hassles, just install and start building.

## ✨ Features

- 🎨 **Modern Landing Page** - Beautiful landing page with hero, features, and pricing sections
- 🔐 **Authentication** - Magic link authentication with Supabase Auth
- 📊 **Dashboard** - Complete dashboard with sidebar navigation and user management
- 🎯 **Protected Routes** - Middleware-based route protection for authenticated pages
- 💅 **Beautiful UI** - Tailwind CSS with Radix UI components for accessibility
- 📱 **Responsive Design** - Mobile-first design that works on all devices
- 🚀 **Ready for Deployment** - Optimized for Vercel deployment

## 🛠️ Tech Stack

- **Framework:** [Next.js 15](https://nextjs.org/) (App Router)
- **Authentication:** [Supabase Auth](https://supabase.com/auth) (Magic Links)
- **Database:** [Supabase](https://supabase.com/)
- **Styling:** [Tailwind CSS](https://tailwindcss.com/)
- **UI Components:** [Radix UI](https://www.radix-ui.com/)
- **Icons:** [Lucide React](https://lucide.dev/)
- **Deployment:** [Vercel](https://vercel.com/)

## 🚀 Getting Started

### Prerequisites

- Node.js 22+ installed (we recommend using [nvm](https://github.com/nvm-sh/nvm))
- Yarn package manager
- A Supabase account (free tier available at [supabase.com](https://supabase.com))
- A Vercel account for deployment (optional)

### Installation

1. **Clone the repository**

```bash
git clone <your-repo-url>
cd vortex
```

2. **Set up Node.js version**

If you're using nvm (recommended):

```bash
nvm use
```

This will automatically use Node.js 22 as specified in `.nvmrc`.

If you don't have Node.js 22 installed:

```bash
nvm install 22
nvm use 22
```

3. **Install dependencies**

```bash
yarn install
```

4. **Set up Supabase**

   - Create a new project at [supabase.com](https://supabase.com)
   - Go to Project Settings > API
   - Copy your project URL and anon key

5. **Configure Magic Link Authentication in Supabase**

   - Go to Authentication > Settings in your Supabase dashboard
   - Enable "Enable email confirmations" for magic links
   - Configure your site URL:
     - For local: `http://localhost:3000`
     - For production: `https://yourdomain.com`

6. **Set up environment variables**

Create a `.env.local` file in the root directory:

```env
NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

7. **Run the development server**

```bash
yarn dev
```

Open [http://localhost:3000](http://localhost:3000) to see your app.

## 📁 Project Structure

```
src/
├── app/
│   ├── auth/                 # Authentication pages
│   │   ├── callback/        # OAuth callback handler
│   │   ├── signin/          # Sign in page
│   │   └── signup/          # Sign up page
│   ├── dashboard/           # Protected dashboard pages
│   │   ├── projects/        # Projects page
│   │   ├── team/           # Team management
│   │   ├── settings/       # User settings
│   │   └── layout.tsx      # Dashboard layout with sidebar
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Landing page
│   └── globals.css         # Global styles
├── components/
│   ├── dashboard/          # Dashboard-specific components
│   │   ├── sidebar.tsx    # Sidebar navigation
│   │   └── actions.ts     # Server actions (logout)
│   └── ui/                # Reusable UI components
│       ├── button.tsx
│       └── card.tsx
├── lib/
│   ├── supabase/          # Supabase client utilities
│   │   ├── client.ts     # Browser client
│   │   └── server.ts     # Server client
│   └── utils.ts          # Utility functions
└── middleware.ts         # Route protection middleware
```

## 🔐 Authentication Flow

1. User enters email and clicks "Send Magic Link"
2. Supabase sends magic link to user's email
3. User clicks link in email, redirected to `/auth/callback`
4. Session established, user redirected to `/dashboard`
5. Middleware protects all `/dashboard/*` routes

## 🎨 Customization

### Branding

Update the following files to customize your branding:

- `src/app/page.tsx` - Landing page content
- `src/app/layout.tsx` - Site metadata and title
- `src/components/dashboard/sidebar.tsx` - Dashboard branding

### Styling

- Tailwind configuration: `tailwind.config.js`
- Global styles: `src/app/globals.css`
- Color scheme: Modify Tailwind classes in components

### Adding Pages

1. Create a new page in `src/app/dashboard/[your-page]/page.tsx`
2. Add navigation item to `src/components/dashboard/sidebar.tsx`

### Magic Link Authentication

The app uses Supabase's magic link authentication:
- No passwords required - users enter email and receive a magic link
- Clicking the link signs them in automatically
- More secure than passwords and better user experience
- Users are redirected through `/auth/callback` after clicking the link

## 🚢 Deployment

### Deploy to Vercel

1. Push your code to GitHub
2. Import your repository to Vercel
3. Add environment variables in Vercel dashboard
4. Deploy!

### Environment Variables for Production

Update `.env.local` with production values:

```env
NEXT_PUBLIC_SUPABASE_URL=your-production-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-production-anon-key
NEXT_PUBLIC_APP_URL=https://yourdomain.com
```

Don't forget to update the OAuth callback URL in your Supabase dashboard!

## 📝 Available Scripts

- `yarn dev` - Start development server
- `yarn build` - Build for production
- `yarn start` - Start production server
- `yarn lint` - Run ESLint

## 🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

## 📄 License

This project is open source and available under the MIT License.

## 🙏 Acknowledgments

- [Next.js](https://nextjs.org/)
- [Supabase](https://supabase.com/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Radix UI](https://www.radix-ui.com/)
- [Lucide Icons](https://lucide.dev/)

## 💬 Support

If you have any questions or need help, please open an issue or reach out to the community.

---

Built with ❤️ using Next.js and Supabase