NextJS Template App

A comprehensive template for scaffolding modern NextJS applications with authentication, payments, and monitoring.

Tech Stack

• Frontend: Next.js 15.4, React 19, TailwindCSS 4, ShadCN UI, Phosphor Icons
• Backend: Next.js API Routes, Server Actions with Next Safe Action
• Database: PostgreSQL with Drizzle ORM
• Authentication: Better Auth with Google OAuth
• Payments: Stripe integration with webhook support
• Email: React Email with Nodemailer
• Form Handling: React Hook Form with Zod validation and Next Safe Action Hook Form adapter
• Rate Limiting: Memory-based rate limiting
• Monitoring: Sentry for error tracking and performance monitoring
• Deployment: Docker support with multi-stage builds
• Development: TypeScript, Biome, Lefthook for git hooks

Getting Started

Prerequisites

• Node.js 22+ and npm (see .nvmrc for exact version)
• PostgreSQL database
• Google OAuth credentials (for authentication)
• Stripe account (for payments)
• SMTP server (for emails)

Development Setup

1. Clone the repository:

   git clone https://github.com/jaqubowsky/create-nextjs-app.git
   cd nextjs-template-app

2. Install dependencies:

   npm install

3. Set up environment variables:

   Create a .env file with the following variables:

   NODE_ENV=development
   SKIP_ENV_CHECK="true"
   
   # Server-only variables (not exposed to client)
   DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
   
   GOOGLE_CLIENT_ID="sample-google-client-id"
   GOOGLE_CLIENT_SECRET="sample-google-client-secret"
   
   BETTER_AUTH_SECRET="sample-secret-key-for-typecheck"
   
   EMAIL_SERVER_HOST="smtp.example.com"
   EMAIL_SERVER_PORT="587"
   EMAIL_SERVER_USER="[email protected]"
   EMAIL_SERVER_PASSWORD="sample-password"
   EMAIL_FROM="[email protected]"
   EMAIL_SERVICE="gmail"
   
   STRIPE_WEBHOOK_SECRET="whsec_sample_webhook_secret"
   STRIPE_SECRET_KEY="sk_test_sample_stripe_key"
   STRIPE_API_VER="2023-10-16"
   
   SENTRY_AUTH_TOKEN="sample-sentry-auth-token"
   
   # Client-side variables (these match the env.production.client file)
   NEXT_PUBLIC_APP_NAME="Sample App"
   NEXT_PUBLIC_COMPANY_NAME="Sample Company"
   
   NEXT_PUBLIC_SENTRY_DSN="https://[email protected]/123"
   NEXT_PUBLIC_SENTRY_PROJECT="sample-project"
   NEXT_PUBLIC_SENTRY_ORG="sample-org"
   
   NEXT_PUBLIC_BETTER_AUTH_URL="http://localhost:3000"

   Note: These are sample values for development. Replace with actual credentials when deploying to production.

4. Generate and apply database migrations:

   npm run db:migrate

5. Start the development server with Turbopack:

   npm run dev

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

Setting Up Release Automation (Optional)

This template includes automated release management using Release Please. To enable it:

1. Enable GitHub Actions Permissions:

   • Go to your repository Settings → Actions → General → Workflow permissions
   • Select "Read and write permissions"
   • Check "Allow GitHub Actions to create and approve pull requests"

2. Create a Personal Access Token (if you encounter permission errors):

   • Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
   • Generate new token (classic) with these scopes: repo (full repository access)
   • Add it as a repository secret named RELEASE_PLEASE_TOKEN
   • Update .github/workflows/release-please.yml to use ${{ secrets.RELEASE_PLEASE_TOKEN }}

3. How Release Please Works:

   • Write commits using conventional commit format (e.g., feat: add new feature, fix: resolve bug)
   • Push to master branch
   • Release Please automatically creates a "Release PR" with updated CHANGELOG.md and version bump
   • When you merge the Release PR, it creates a GitHub release and git tag

Available Scripts

• npm run dev - Start development server with Turbopack and database studio
• npm run next:dev - Start Next.js development server with Turbopack only
• npm run build - Build the application for production
• npm run start - Start the production server
• npm run typecheck - Run TypeScript type checking
• npm run lint - Run Biome linter
• npm run lint:fix - Run Biome linter with comprehensive fixes
• npm run db:generate - Generate Drizzle migration files
• npm run db:migrate - Generate and apply database migrations
• npm run db:migrate:prod - Run production database migrations
• npm run db:studio - Open Drizzle Studio for database management
• npm run db:reset - Reset database (WARNING: deletes all data)
• npm run commit - Interactive commit with Commitizen
• npm run commitlint - Lint commit messages

Project Structure

The project follows a feature-based architecture:

src/
├── app/                    # Next.js App Router pages and layouts
│   ├── api/               # API routes
│   ├── auth/              # Authentication pages
│   └── ...
├── components/            # Shared UI components
├── features/              # Feature modules
│   └── auth/              # Authentication feature
│       ├── actions.ts     # Server actions
│       ├── components/    # Feature-specific components
│       ├── queries.ts     # Feature-specific database queries
│       └── schemas.ts     # Feature-specific zod schemas
├── lib/                   # Utility functions and configurations
│   ├── env.ts            # Environment variables validation
│   ├── stripe.ts         # Stripe configuration
│   ├── rate-limit.ts     # Rate limiting utilities
│   └── ...
├── server/                # Server-side shared utilities
│   └── stripe/           # Stripe server utilities
└── drizzle/              # Database schema and migrations

Features

Authentication

• Google OAuth integration
• Email/password authentication
• Password reset functionality
• Rate-limited authentication endpoints

Payments

• Stripe integration with webhook support
• Customer management
• Subscription handling
• Invoice management

Email System

• React Email templates
• SMTP configuration with Nodemailer
• Transactional emails

Rate Limiting

• Memory-based rate limiting
• Configurable limits per endpoint
• IP-based request tracking

Monitoring

• Sentry integration for error tracking
• Performance monitoring
• Custom error boundaries

Docker Deployment

The project includes Docker support with multi-stage builds for optimal production deployments:

# Build the Docker image
docker build -t nextjs-template-app .

# Run the container
docker run -p 3000:3000 nextjs-template-app

Environment Variables

The project uses T3 Env for runtime environment variable validation. Variables are categorized into:

• Server: Only available on the server side
• Client: Available on both client and server (prefixed with NEXT_PUBLIC_)
• Shared: Available in both environments with proper validation

License

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

Acknowledgements

• Next.js
• React
• Drizzle ORM
• TailwindCSS
• ShadCN UI
• Better Auth
• Stripe
• Sentry
• React Email