create-prospana-app

A powerful CLI tool for scaffolding production-ready Next.js applications with built-in authentication, database integration, and modern UI components.

Features

• One-Command Setup - Create a fully configured Next.js app in minutes
• Multiple Database Providers - Choose between Supabase, PostgreSQL (Local/Docker), or Neon
• Flexible ORM Options - Select Prisma or Drizzle for type-safe database operations
• Built-in Authentication - Pre-configured authentication with Better Auth or Supabase Auth
• Google OAuth Support - Optional social authentication with Google
• Pre-built Dashboard - Responsive dashboard layout with example pages
• Theme Customization - Light/Dark/System mode with multiple color schemes
• AI Integration - Optional OpenAI API integration for AI-powered features
• ShadCN UI Components - Beautiful, accessible components built with Radix UI
• Automatic Database Setup - Automatic PostgreSQL database creation and migration
• TypeScript First - Fully typed codebase with TypeScript
• Modern Stack - Next.js 15 with App Router, Tailwind CSS, and more

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18.0.0 or higher
• PostgreSQL (if using local PostgreSQL option)
• Database credentials ready for your chosen database provider

Quick Start

Run the following command to create a new Prospana app:

npx create-prospana-app

The CLI will guide you through an 8-step interactive setup process.

Configuration Options

Step 1: Project Name

Enter your desired project name (default: my-app)

[1/8] Please enter your project name: my-awesome-app

Step 2: Database Provider

Choose your preferred database provider:

• Supabase (Recommended - Fastest Setup) - Managed PostgreSQL with built-in authentication
• PostgreSQL (Local or Docker) - Self-hosted PostgreSQL database
• Neon (Serverless PostgreSQL) - Serverless PostgreSQL platform

[2/8] Choose your database provider:
o Supabase (Recommended - Fastest Setup)
  PostgreSQL (Local or Docker)
  Neon (Serverless PostgreSQL)

Step 3: ORM Selection

(Only for PostgreSQL and Neon)

Choose your preferred ORM:

• Prisma - Migration-based ORM with excellent TypeScript support
• Drizzle - TypeScript-first ORM with a lightweight footprint

[3/8] Choose your ORM:
o Prisma
  Drizzle

Database Configuration

For PostgreSQL (Local/Docker):

Enter your database host name: localhost
Enter your database name: my_database
Enter your database port: 5432
Enter your database username: postgres
Enter your database password: ********

For Supabase:

Enter your Supabase URL: https://xxxxx.supabase.co
Enter your Supabase anon key: ********
Enter your Supabase service role key: ********

For Neon:

Enter your database hostname: ep-your-project.us-east-2.aws.neon.tech
Enter your database name: neondb
Enter your database username: your_username
Enter your database password: ********

Step 4: Google OAuth (Optional)

Enable Google OAuth for social authentication:

[4/8] Do you want to set up Google OAuth? (y/N)
Enter your Google Client ID: your-client-id.apps.googleusercontent.com
Enter your Google Client Secret: ********

Step 5: AI Features (Optional)

Enable OpenAI integration for AI-powered features:

[5/8] Do you want to set up AI features? (y/N)
Enter your OpenAI API key: sk-********
Set default model: gpt-4o-mini

Step 6: Theme Configuration

Choose your default theme mode:

[6/8] Choose default theme mode:
o System
  Light
  Dark

Then choose your base color scheme:

Choose your base color:
o Neutral
  Gray
  Zinc
  Stone
  Slate

Step 7: Vercel Deployment (Optional)

Configure Vercel deployment for your application:

[7/8] Do you want to set up Vercel deployment configuration? (y/N)
Enter Vercel project name: my-awesome-app
Enable Vercel Analytics and Web Vitals? (Y/n)
Initialize Git repository? (Y/n)
Configure production environment variables? (y/N)
ℹ You can add production vars later at: vercel.com/dashboard

Note: Vercel deployment configuration is optional and defaults to "No". If you skip this step, you can still deploy to Vercel manually later.

Step 8: Configuration Summary

Review your configuration before generation:

============================================================
[8/8] Configuration Summary
============================================================

📦 Project Configuration:
   • Name: my-awesome-app
   • Database: PostgreSQL (Local or Docker)
   • ORM: Prisma
   • Theme: System (Neutral)
   • Google OAuth: ✅ Enabled
   • AI Features: ❌ Disabled
   • Vercel Deployment: ✅ Configured
   • Vercel Analytics: ✅ Enabled
   • Git Repository: ✅ Will be initialized

🚀 Generating your Prospana app...
============================================================

The setup will automatically proceed to project generation after displaying the summary. No confirmation required!

Database Providers

Supabase

Recommended for fastest setup

• Managed PostgreSQL database
• Built-in authentication system
• Real-time subscriptions
• Automatic API generation
• Free tier available

Setup Instructions:

1. Create a free account at supabase.com
2. Create a new project
3. Copy your project URL and API keys from Settings > API
4. Enable Email Auth and Google OAuth (if needed) in Authentication > Providers

PostgreSQL (Local/Docker)

Best for local development

• Full control over database
• No external dependencies
• Automatic database creation
• Works with local or Docker PostgreSQL

Setup Instructions:

1. Install PostgreSQL locally or run with Docker:

   docker run --name postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres

2. The CLI will automatically create the database and run migrations

Neon

Best for serverless deployments

• Serverless PostgreSQL
• Automatic scaling
• Branch support for development
• Free tier available

Setup Instructions:

1. Create a free account at neon.tech
2. Create a new project
3. Copy your connection string from the dashboard
4. During setup:
   • Choose your migration strategy (Prisma)
   • Optionally test connection before setup
5. Tables are created automatically - ready to use immediately!

ORM Options

Prisma

Migration-based ORM

• Schema-first approach
• Automatic migrations
• Excellent TypeScript support
• Rich query capabilities
• Visual database studio

Generated Files:

• prisma/schema.prisma - Database schema
• Automatic migration files

Commands:

npx prisma studio          # Open visual database editor
npx prisma migrate dev     # Create new migration
npx prisma generate        # Regenerate Prisma Client

Drizzle

TypeScript-first ORM

• Lightweight and fast
• SQL-like query syntax
• No additional runtime overhead
• Schema push without migrations

Generated Files:

• src/lib/db/schema.ts - Database schema
• drizzle.config.ts - Drizzle configuration

Commands:

npx drizzle-kit studio     # Open visual database editor
npx drizzle-kit push       # Push schema changes
npx drizzle-kit generate   # Generate migration files

Authentication

Better Auth

Used with PostgreSQL and Neon

• Modern authentication library
• Built for Next.js App Router
• Email/password authentication
• Google OAuth support
• Session management
• Type-safe API

Generated Files:

• src/lib/auth.ts - Auth configuration
• src/app/api/auth/[...all]/route.ts - Auth API routes
• src/actions/auth.ts - Server actions

Supabase Auth

Used with Supabase

• Built into Supabase platform
• Email/password authentication
• Social OAuth providers
• Magic link authentication
• Row Level Security (RLS)

Generated Files:

• src/lib/supabase/client.ts - Client-side Supabase client
• src/lib/supabase/server.ts - Server-side Supabase client
• src/actions/auth.ts - Server actions
• src/app/auth/callback/route.ts - OAuth callback handler

Generated Project Structure

your-app/
�� src/
   �� app/
      �� (auth)/
         �� layout.tsx          # Auth pages layout
         �� login/
            �� page.tsx        # Login page
         �� register/
             �� page.tsx        # Register page
      �� (dashboard)/
         �� layout.tsx          # Dashboard layout with nav
         �� dashboard/
            �� page.tsx        # Dashboard home
         �� settings/
             �� page.tsx        # Settings page
      �� auth/
         �� [...all]/
            �� route.ts        # Better Auth API routes
         �� callback/
             �� route.ts        # Supabase OAuth callback
      �� layout.tsx              # Root layout with theme
      �� page.tsx                # Landing page
      �� globals.css             # Global styles
   �� actions/
      �� auth.ts                 # Auth server actions
   �� components/
      �� ui/                     # ShadCN UI components
      �� dashboard-nav.tsx       # Dashboard navigation
      �� google-oauth-button.tsx # Google OAuth button
      �� nav-header.tsx          # Navigation header
      �� theme-provider.tsx      # Theme context provider
      �� theme-toggle.tsx        # Theme toggle button
      �� theme-settings.tsx      # Theme settings component
   �� lib/
      �� db/                     # Database (Drizzle)
         �� schema.ts           # Drizzle schema
         �� index.ts            # Database client
      �� supabase/               # Supabase clients
         �� client.ts           # Client-side client
         �� server.ts           # Server-side client
      �� auth.ts                 # Better Auth config
      �� auth-client.ts          # Better Auth client
      �� dal.ts                  # Data Access Layer
      �� utils.ts                # Utility functions
   �� middleware.ts               # Route protection
�� prisma/
   �� schema.prisma               # Prisma schema (if using Prisma)
�� drizzle.config.ts               # Drizzle config (if using Drizzle)
�� .env.local                      # Environment variables
�� next.config.ts                  # Next.js configuration
�� tailwind.config.ts              # Tailwind configuration
�� tsconfig.json                   # TypeScript configuration
�� package.json                    # Dependencies

Tech Stack

Core

• Next.js 15 - React framework with App Router
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework

Database & ORM

• Prisma - Next-generation ORM
• Drizzle - TypeScript ORM
• PostgreSQL - Relational database
• Supabase - Backend as a Service
• Neon - Serverless PostgreSQL

Authentication

• Better Auth - Modern auth library for Next.js
• Supabase Auth - Built-in authentication

UI Components

• ShadCN UI - Re-usable components built with Radix UI
• Radix UI - Unstyled, accessible components
• Lucide Icons - Beautiful icon library
• next-themes - Theme management

AI (Optional)

• OpenAI API - AI capabilities

Environment Variables

The CLI automatically generates a .env.local file with the following variables based on your configuration:

PostgreSQL/Neon

# Database Configuration
DATABASE_URL=postgresql://username:password@hostname:5432/database

# Better Auth Configuration
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=<auto-generated>

# Google OAuth Configuration (if enabled)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

# AI Configuration (if enabled)
OPENAI_API_KEY=sk-your-api-key
OPENAI_MODEL=gpt-4o-mini

Supabase

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Google OAuth Configuration (if enabled)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

# AI Configuration (if enabled)
OPENAI_API_KEY=sk-your-api-key
OPENAI_MODEL=gpt-4o-mini

Post-Setup Instructions

For Supabase

1. Navigate to your project:

   cd your-app

2. Configure authentication in your Supabase dashboard:

   • Enable Email Auth provider
   • Enable Google OAuth provider (if you set it up)
   • Add authorized redirect URL: http://localhost:3000/auth/callback

3. Start the development server:

   npm run dev

For PostgreSQL (Local)

1. Navigate to your project:

   cd your-app

2. Start the development server (database and tables are already created):

   npm run dev

For Neon

1. Navigate to your project:

   cd your-app

2. Start the development server (tables already created):

   npm run dev

Note: Database tables are created automatically during setup. If setup failed or was skipped:

• Prisma: npx prisma migrate dev or npx prisma migrate deploy
• Drizzle: npx drizzle-kit push

Your app will be available at http://localhost:3000

Vercel Deployment

If you enabled Vercel deployment configuration during setup, your project includes:

• vercel.json - Vercel configuration with build settings and environment variables
• .vercelignore - Files to exclude from deployment
• DEPLOYMENT.md - Comprehensive deployment guide with database-specific instructions

Quick Deployment

Option 1: Deploy via Vercel Dashboard (Recommended)

1. Push to GitHub:

   cd your-app
   git remote add origin https://github.com/yourusername/your-app.git
   git branch -M main
   git push -u origin main

   Note: If you enabled Git initialization during setup, your repository is already initialized with an initial commit.

2. Import to Vercel:

   • Go to vercel.com/new
   • Import your repository
   • Vercel will auto-detect Next.js and use your vercel.json configuration
   • Add environment variables in the dashboard (see DEPLOYMENT.md for details)
   • Click "Deploy"

Option 2: Deploy via Vercel CLI

1. Install Vercel CLI:

   npm i -g vercel

2. Login and Deploy:

   cd your-app
   vercel login
   vercel

3. Add Environment Variables: Follow the prompts or see DEPLOYMENT.md for CLI commands to add environment variables.

4. Deploy to Production:

   vercel --prod

Database Considerations for Production

• Supabase: Works out-of-the-box with serverless deployments. Consider installing the Vercel x Supabase Integration.
• Neon: Enable connection pooling in your Neon dashboard and use the pooled connection string in Vercel.
• PostgreSQL: Use a connection pooler (PgBouncer) or migrate to a serverless-friendly database like Neon or Supabase.

Post-Deployment Checklist

After deploying, make sure to:

1. ✅ Update BETTER_AUTH_URL (or OAuth redirect URLs) to your production domain
2. ✅ Update Google OAuth redirect URLs in Google Cloud Console
3. ✅ Test authentication flows in production
4. ✅ Verify database connections are working
5. ✅ Check environment variables are set correctly
6. ✅ Monitor Vercel Analytics (if enabled)

For detailed deployment instructions, see the DEPLOYMENT.md file in your project.

Google OAuth Setup

To enable Google OAuth, you need to create OAuth credentials in Google Cloud Console:

1. Create Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one

2. Configure OAuth Consent Screen

1. Navigate to APIs & Services > OAuth consent screen
2. Select External user type
3. Fill in the required fields:
   • App name
   • User support email
   • Developer contact information
4. Add scopes: email, profile, openid

3. Create OAuth Credentials

1. Navigate to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. Select Web application
4. Add authorized redirect URIs:
   • For Better Auth: http://localhost:3000/api/auth/callback/google
   • For Supabase: http://localhost:3000/auth/callback
   • Add production URLs when deploying
5. Copy the Client ID and Client Secret

4. Add Credentials to Your App

Use these credentials when running create-prospana-app or add them to .env.local:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Development

Building the Project

npm run build

This compiles TypeScript and copies template files to the dist/ directory.

Testing Locally

npm run link

This builds the project and creates a global symlink, allowing you to test with:

create-prospana-app

Project Scripts

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript and copy templates | | npm run copy-templates | Copy template files to dist | | npm run link | Build and create global symlink |

Troubleshooting

Database Connection Issues

Problem: Can't connect to PostgreSQL database

Solution:

• Verify PostgreSQL is running: pg_isready
• Check credentials in .env.local
• Ensure database exists: psql -U postgres -c "\l"

Prisma DATABASE_URL Error

Problem: Environment variable not found: DATABASE_URL

Solution:

• This should be automatically handled by the CLI
• If it persists, manually add DATABASE_URL to .env
• Ensure .env.local contains the correct connection string

Supabase Auth Not Working

Problem: Google OAuth redirects fail

Solution:

• Verify redirect URL in Google Cloud Console matches: http://localhost:3000/auth/callback
• Enable Google OAuth in Supabase dashboard: Authentication > Providers > Google
• Check that GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set in Supabase dashboard

ShadCN Component Issues

Problem: Components not rendering correctly

Solution:

• Ensure all dependencies are installed: npm install
• Check that Tailwind CSS is properly configured
• Verify globals.css is imported in layout.tsx

Type Errors

Problem: TypeScript errors in generated code

Solution:

• Regenerate database client:
  • Prisma: npx prisma generate
  • Drizzle: npm run build
• Restart TypeScript server in your IDE
• Clear .next folder: rm -rf .next

Contributing

We welcome contributions to create-prospana-app! Here's how you can help:

Development Setup

1. Clone the repository:

   git clone https://github.com/prospana/create-prospana-app.git
   cd create-prospana-app

2. Install dependencies:

   npm install

3. Make your changes to index.ts, create-app.ts, or template files

4. Build and test:

   npm run link
   create-prospana-app

Guidelines

• Follow existing code style and conventions
• Test your changes thoroughly with all database/ORM combinations
• Update documentation if adding new features
• Keep template files consistent with the tech stack

Reporting Issues

If you encounter a bug or have a feature request:

1. Check if the issue already exists
2. Create a new issue with:
   • Clear description
   • Steps to reproduce (for bugs)
   • Expected vs actual behavior
   • Your environment (Node version, OS, etc.)

License

ISC License

Copyright (c) 2024 Prospana

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

Support

Need help? We're here for you:

• Email: [email protected]
• GitHub Issues: Report a bug or request a feature
• Documentation: This README and inline code comments

Acknowledgments

Built with love by the Prospana team using these amazing open-source projects:

• Next.js
• Prisma
• Drizzle
• Better Auth
• Supabase
• ShadCN UI
• Tailwind CSS

Made with d by Prospana