DEV Community

Cover image for I Built a Next.js SaaS Boilerplate So You Don't Have To - 3 Month Journey
Muhammad Zubair
Muhammad Zubair

Posted on

I Built a Next.js SaaS Boilerplate So You Don't Have To - 3 Month Journey

#react #nextjs #typescript #beginners

After spending 3 months building, debugging, and deploying, I finally launched FreelanceHub - a production-ready Next.js SaaS boilerplate.

🤔 Why I Built This

I kept rebuilding the same features across different projects:

  • Authentication flows (email, OAuth, sessions)
  • Payment processing (Stripe, webhooks, subscriptions)
  • Database setup (schema, migrations, queries)
  • Client management (CRUD operations)
  • Modern UI components

Every project took 2-3 months just to get the foundation working. I realized I could package everything into a reusable starter kit.

🚀 What's Included

Authentication

  • Clerk integration (email, OAuth, magic links)
  • Protected routes
  • User profile management
  • Session management

Payments

  • Stripe checkout + subscriptions
  • Webhook handling
  • Customer portal
  • Multiple pricing tiers

Database

  • PostgreSQL with Prisma ORM
  • Type-safe queries
  • Migration scripts
  • Optimized schema

UI/UX

  • Beautiful dark theme
  • shadcn/ui components
  • Fully responsive design
  • Loading states & error handling

Features

  • Client CRM with CRUD
  • Time tracking system
  • Dashboard with analytics
  • Settings & profile management

💻 Tech Stack

  • Framework: Next.js 16 with App Router
  • Language: TypeScript
  • Styling: Tailwind CSS + shadcn/ui
  • Database: PostgreSQL + Prisma
  • Auth: Clerk
  • Payments: Stripe
  • Deployment: Netlify (but works on Vercel, Railway, etc.)

😤 The Hard Lessons

1. Vercel + Clerk Edge Runtime Issues

Ran into major compatibility problems with Clerk middleware on Vercel's Edge runtime. After days of debugging, switched to Netlify and everything worked perfectly.

Takeaway: Not all hosting platforms handle middleware the same way!

2. Stripe Webhooks Are Tricky

Testing webhooks locally was painful until I discovered Stripe CLI. Game changer for development.

stripe listen --forward-to localhost:3000/api/stripe/webhooks
Enter fullscreen mode Exit fullscreen mode

3. Database Migrations in Production

Learned the hard way that Prisma needs prisma generate in the build process on CI/CD platforms. Added to build script:

"build": "prisma generate && next build"
Enter fullscreen mode Exit fullscreen mode

4. useSearchParams Needs Suspense

Next.js 16's stricter rendering rules caught me. Had to wrap client components using useSearchParams() in Suspense boundaries.

🎯 What Makes It Different

It's production-ready, not just a template:

  • ✅ Actually deployed and tested
  • ✅ Handles edge cases
  • ✅ Includes error boundaries
  • ✅ Proper loading states
  • ✅ TypeScript throughout
  • ✅ Comprehensive documentation

📊 Live Demo

Check it out: FreelanceHub Demo

The demo showcases:

  • Responsive landing page
  • Feature sections
  • Pricing tiers
  • FAQ section

🤓 Technical Deep Dive

Project Structure 

├── app/                    # Next.js 16 App Router
│   ├── api/               # API routes
│   ├── dashboard/         # Protected pages
│   └── (public)/          # Public pages
├── components/            # React components
├── lib/                   # Utilities & configs
├── prisma/               # Database schema
└── public/               # Static assets
Enter fullscreen mode Exit fullscreen mode

Key Features Implementation

Authentication Flow:

  • Clerk handles all auth UI
  • Middleware protects routes
  • User data synced to database

Payment Flow:

  • Stripe Checkout for subscriptions
  • Webhooks update user plan in DB
  • Customer portal for management

Database Schema:

  • User → Clients (one-to-many)
  • Client → TimeEntries (one-to-many)
  • Prisma relations handle cascading

💡 What I'd Build Next

If I continue developing this:

  1. Invoice generation (PDF exports)
  2. Email notifications (Resend integration)
  3. Team collaboration features
  4. API for third-party integrations
  5. Mobile app (React Native?)

🙏 Feedback Welcome

I'd love to hear your thoughts:

  • Is the tech stack solid?
  • What features would you add?
  • Any architecture improvements?

Also curious about pricing. I set it at $149 (one-time payment). Too high? Too low? Fair?

🔗 Links

🎉 Final Thoughts

Building this taught me more than any tutorial ever could. The deployment issues, payment integration challenges, and edge cases forced me to really understand the stack.

If you're building a SaaS and want to skip the boring setup part, check it out! And if you have questions about the implementation, happy to answer in the comments! 🚀

Thanks for reading! Follow me for more dev content! ✨

Top comments (0)