Overview

Easy-to-setup, fully-featured, and customizable NextJS Boilerplate

This page was last updated on: 31st May 2025

DO NOT upgrade any dependencies in your package.json for the core stack dependencies (Clerk, Stripe, Supabase, etc.), unless you have a specific reason to and are following the official migration guides from each service. Upgrading packages without proper migration can break your authentication, payments, database connections, and other critical functionality. The current versions in the boilerplate are tested and stable together.

Repo: https://github.com/ObaidUr-Rahmaan/titan

Pre-requisites

1. Frontend Knowledge (Have completed the Frontend section of the Software Engineer Roadmap) so that you’re base HTML, CSS, JS and React skills are up to par.
2. Fundamental Backend Systems Knowledge (Have completed the Systems Expert Fundamentals Course of the Software Engineer Roadmap)
3. Know SQL, specifially PostgreSQL (Go through this course -> Datacamp)
4. Fundamental NextJS Knowledge (Have completed the interactive NextJS Course on the nextjs.org website)

Tech Stack

• NextJS 15 - Full-Stack React framework
• Supabase - Database as a Service Provider
• Clerk - Authentication as a Service Provider
• Stripe + ByeDispute / Chargeblast - Payments as a Service Provider + Dispute Resolution
• Plunk - Email as a Service Provider
• DataFast - User Analytics for Actionable Growth (Know exactly which marketing channels are working)
• Vercel - Deployments without worrying about infrastructure (Auto-Scaling, DDoS protection, etc.)

Cost of running this stack

All of the above services (except GetFernand) have generous free tiers.

Even as your product grows, the cost remains minimal (averaging $300-400/month with 10,000+ DAUs for 80%+ profit margin).

These 3rd party services abstract away significant infrastructure work in key areas (payments, authentication, database, etc.), letting you focus solely on building your product.

For niche industries like healthcare, additional compliance might be required. Supabase offers HIPAA-compliant databases for $599/month.

See this Article for more information on Supabase’s SOC2 and HIPAA compliance if you’re considering building a healthcare app.

Building with Titan

1. Prerequisites

   1. Install the latest stable version of Node.js (If you already have Node.js installed, this will override it):

      • Mac/Linux: Install via nvm:
        nvm install stable
        

      Verify Node.js is installed:

      node -v
      

      Should return something like v24.x.y (at the time of writing: 24.1.0)

   2. Install Bun: We recommend using Bun for significantly faster development experience - including 10x faster dependency installation, 2-4x faster builds, and practically instant dev server startup.

   # For macOS
   curl -fsSL https://bun.sh/install | bash
   
   # Verify Bun is installed:
   bun -v
   

   Should return something like 1.x.y (at the time of writing: 1.2.15)

   3. Create a new empty GitHub repository for your project

      Have the SSH repository URL ready (e.g., [e-mail]:username/repo-name.git)

      Make sure it’s the SSH URL, not the HTTPS URL!

   4. Install the Supabase CLI to interact with Supabase:

      • Install via Homebrew:
        brew install supabase/tap/supabase
        

   5. Gather your Development API keys from the following services:

   If you have your own agency and you’re building for a client, you’ll need to create all the below accounts for them using your own agency company email account and then transfer ownership to them later when the contract ends.

   See the Account Management Guide for more information on how to do this.

   • Clerk (Authentication)

     • Create an account at Clerk (or new ‘Application’ if you already have an account)
     • Create a new Application but and select all the different sign in methods you’d like to support (Google, Apple, Email, etc.)
     • Copy your NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY from the ‘API Keys’ section.
     • Add them to somewhere safe (ideally if you’re using a clipboard manager, you’ll be able to paste them into your .env file later)
     We’ll get to the CLERK_WEBHOOK_SECRET when we’re testing the app locally and deploying to production. Leave it blank for now.

   • Stripe (Payments)

     • Create an account at Stripe (if you don’t have one already)
     • Make sure you’re in the test-mode dashboard
     • Copy your STRIPE_SECRET_KEY and NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY from the ‘API Keys’ section (‘Developers’ -> ‘API Keys’)
     • Create a product and get your NEXT_PUBLIC_STRIPE_PRICE_ID
     • Configure your Stripe Customer Portal (2-minute setup):
       • Go to Stripe Customer Portal Settings
       • Click “Activate test link” to enable the customer portal
       • Save the settings
     • Add them to somewhere safe (ideally if you’re using a clipboard manager, you’ll be able to paste them into your .env file later)

   The Customer Portal allows your users to manage their billing, update payment methods, view invoices, and cancel subscriptions without you having to build these features from scratch.

   We’ll get to the STRIPE_WEBHOOK_SECRET when we’re testing the app locally and deploying to production. Leave it blank for now.

   • Plunk (Email)
     • Create an account at Plunk
     • Copy the ‘secret’ PLUNK_API_KEY from Project Settings > API Keys
     • Add them to somewhere safe (ideally if you’re using a clipboard manager, you’ll be able to paste them into your .env file later)
   • Supabase (Database)
     • Create an account at Supabase
     • Create a new project called ‘[Project Name] Dev DB’
     • When creating your database password, avoid special characters like ’#’ and ’&’ as they cause URL encoding issues
     • Copy your database password and keep it safe (ideally in a password manager)
     • Copy your NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY from the ‘Connect’ modal on the main Project Dashboard page (click on the ‘Connect’ button) and then go to the ‘App Frameworks’ tab
     • Copy your SUPABASE_SERVICE_ROLE_KEY from the Project Settings > API Keys tab
     • Copy your DATABASE_URL (with pgbouncer) and DIRECT_URL (without pgbouncer) from the same ‘Connect’ modal under the ‘ORMs’ tab
     • Make sure to replace the ‘[YOUR-PASSWORD]’ part of it, with your actual database password
     • Add them to somewhere safe (ideally if you’re using a clipboard manager, you’ll be able to paste them into your .env file later)
2. Setup via CLI

   1. Using your previously saved info (GitHub repo URL and API keys), create your project locally by running:
      bun x @codeandcreed/create-titan@latest
      

   You’ll be given the option add your API keys during the setup process, or manually later in your .env file.

   2. Follow the prompts to configure your project. The CLI will:
      1. Clone the project template
      2. Create the .env file with all the required environment variables

   Done! Your project is now set up:

   • Pushed to your GitHub repo ✅
   • Ready for local development ✅

   Make sure to add all of the above API keys to your .env file before you start local development.

   Now GO BACK to the MVP Development Guide and continue to step ‘Requirements & Documentation’ and continue until step Setup Local Development Tools & Build MVP

   Once you’ve completed the initial editor setup, you can go back to the Titan Guide and continue from step ”

3. Developing your app locally

   Run your app locally

   bun run dev
   

   Setup ngrok

   When we run the app later, all requests will be forwarded to ngrok and then to your local app. ngrok is necessary for the auth and payments webhooks to work.

   It’s also best to use either incognito (to prevent any extensions from interfering with the app) or a new browser profile OR Sizzy (Paid), as it allows extensive testing across different devices.

   1. Install ngrok (if you don’t have it already):
      • Install via Homebrew: brew install ngrok
   2. Run your dev server:
      bun run dev
      

   3. Open a new terminal (outside of Cursor) and run ngrok http 3000
   4. Copy the ngrok URL.
   5. Update the FRONTEND_URL environment variable in your .env file to the ngrok URL.

   This will be your local development URL (e.g. https://1234567890.ngrok-free.app)

   The reason we need this is to expose our localhost to the public internet, so that we can setup Clerk and Stripe webhooks (which will both send requests to our app in order for us to store those details in our database).

   We need to also have the webhooks configured for both Clerk and Stripe so we can test the authentication and payments flows locally.

   For Clerk:

   • go to Configure -> Webhooks -> + Add Endpoint
   • Set the Endpoint URL to https://[your-ngrok-url]/api/auth/webhook
   • Set the Events to user.created and user.updated
   • Click Create
   • Copy the webhook secret for your environment variables and update the CLERK_WEBHOOK_SECRET in your .env file.

   For Stripe:

   • run stripe listen --forward-to [your-ngrok-url]/api/payments/webhook in a new terminal (outside of Cursor)
   • Copy the webhook secret in the terminal and update the STRIPE_WEBHOOK_SECRET in your .env file.

   Important: When returning to work on your project

   Each time you restart ngrok, it generates a new URL. You must:

   1. Update the FRONTEND_URL in your .env file with the new ngrok URL
   2. Update your webhook endpoints in:
      • Clerk Dashboard: Go to Webhooks and update the endpoint URL. Then update the CLERK_WEBHOOK_SECRET in your .env file.
      • Stripe CLI command: Run stripe listen --forward-to [the-new-ngrok-url]/api/payments/webhook in a new terminal (outside of Cursor) and copy the webhook secret in the terminal and update the STRIPE_WEBHOOK_SECRET in your .env file.
   3. Restart your dev server after updating the .env file

   Failing to update these will cause authentication and payment webhooks to fail silently!

   Configure your app components in order

   Your app requires several components to be set up in the correct order:

   1. First, set up your Database - See the Database Guide for setting up all your tables

   2. Next, configure Authentication - See the Authentication Guide to set up Clerk authentication

   3. Next, set up Payments - See the Payments Guide to configure Stripe payments and Dispute prevention with ByeDispute / Chargeblast

   4. Next, set up Emails - See the Email Guide to configure Plunk emails

   5. Next, set up User Analytics - See the Analytics Guide to configure DataFast (Optional for now as this is paid only)

   6. Next, set up User Feedback - See the Feedback Guide to configure UserJot

   7. Finally, set up Customer Support - See the Customer Support Guide to configure GetFernand

   You must follow this order because your payments system depends on authenticated users, which in turn depend on properly configured database tables.

   Done. Your app will now be able to receive webhooks from both Clerk and Stripe.

   Remember to always use the ngrok url when testing locally (not localhost:3000)

4. Building the Product

   At this point, you should have a clean and beautiful landing page that explains the product and what it does (perhaps with a waitlist setup with Clerk)

   But it’s up to you to now add the main functionality of your product (perhaps a Dashboard that users get redirected to after signing up, and all other relevant pages)

   We’ve got a dedicated guide page related to building clean and beautiful UIs very quickly: Rapid UI Prototyping

   See the ‘The v0 + Cursor Workflow (Recommended)’ section

5. Deploying the App to Production

   You’ll need to purchase a domain before deploying to production. Services like Clerk and Stripe require a verified domain for production environments. Purchase a domain from providers like Namecheap, Porkbun, GoDaddy, or Google Domains before proceeding with production deployment.

   When you’re ready to deploy your application to production, follow our comprehensive deployment guide:

   Deploy to Production Guide

   The guide covers everything you need for a successful production deployment:

   • Domain purchase and setup
   • Production database configuration
   • Production authentication setup
   • Production payments setup
   • Vercel deployment
   • Post-deployment verification
6. Setup Analytics

   Track your site visitors and get insights on how they interact with your site.

   1. Create an account at DataFast
   2. Copy the Tracking code and paste it into the head of your index.html file
   3. Deploy your site
   4. Done. Real-time traffic data should now be being tracked.
7. Gather User Feedback

   1. Create an account at UserJot
   2. Create a new Workspace for the app
   3. Done. Go to ‘My Board’ to see your public feedback/roadmap board.

Future Improvements (Coming soon…)

• Creating Waitlists with Clerk
• Feature flag integration + Recommended usage
• Integrate Zustand for state management client-side
• Implement stronger security rules with ArcJet (Bot detection, Rate limiting, Data Redaction, Email Validation, Application-level DDoS protection, etc.)
• Create a Biome security linting plugin for automatically finding and fixing security issues + integrate into Stack
• Add option for Kinde integration (for those who have more complex RBAC needs)

Assistant

Responses are generated using AI and may contain mistakes.