Modern Web Application Starter Template

🚀 Production-ready Next.js 14+ starter with authentication, database, email, error tracking, and comprehensive testing.

Build your next SaaS, dashboard, or web application in minutes, not weeks.

Live Demo • Documentation • Report Bug

✨ What's Included

This template comes with everything you need to build a modern web application:

🔐 Authentication

Stack Auth integration with Google & GitHub OAuth
Protected routes with middleware
User profile management
Session handling

🗄️ Database

PocketBase integration with type-safe queries
Real-time subscriptions
File upload/storage
Example schema included

📧 Email Service

Resend integration
React Email templates
Welcome email included

🐛 Error Tracking

Sentry integration (client & server)
Error boundaries
Session replay
Performance monitoring

🧪 Testing & CI/CD

Jest for unit tests
Playwright for E2E tests
GitHub Actions CI/CD pipeline
Pre-commit hooks with Husky

🎨 UI/UX

40+ shadcn/ui components
Dark/light mode toggle
Fully responsive design
Loading states & animations

⚡ Developer Experience

TypeScript strict mode
ESLint + Prettier configured
Hot reload
Conventional commits
VS Code settings included

🚀 Quick Start

Get up and running in 5 minutes:

1. Clone & Install

# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git my-app
cd my-app
pnpm install

2. Setup Environment Variables

# Copy the example environment file
cp .env.local.example .env.local

Edit .env.local with your credentials (all services have free tiers):

# Stack Auth - Get from https://app.stack-auth.com/
NEXT_PUBLIC_STACK_PROJECT_ID=your_project_id
NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=your_publishable_key
STACK_SECRET_SERVER_KEY=your_secret_key

# PocketBase - Download from https://pocketbase.io/docs/
NEXT_PUBLIC_POCKETBASE_URL=http://localhost:8090

# Sentry - Get from https://sentry.io/
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn

# Resend - Get from https://resend.com/
RESEND_API_KEY=your_resend_api_key

Need help? See the detailed setup guide with step-by-step instructions for each service.

3. Setup PocketBase (Local Development)

# Download PocketBase from https://pocketbase.io/docs/
# Then run it:
./pocketbase serve

# Access admin UI at http://localhost:8090/_/
# Import schema from POCKETBASE_SETUP.md

4. Start Development Server

pnpm dev

Visit http://localhost:3000 - you should see the homepage!

5. Verify Everything Works

# Run type checking
pnpm type-check

# Run linting
pnpm lint

# Run tests
pnpm test

# Build for production
pnpm build

All green? You're ready to start building!

🎓 Next Steps

Now that you're set up, here's what to do next:

Explore the App
- Try logging in with Google/GitHub OAuth
- Check out the dashboard at /dashboard
- View your profile at /dashboard/profile
- Toggle dark/light mode
Customize Your App
- Update app name in app/layout.tsx
- Modify colors in app/globals.css
- Replace logo in components/layout/sidebar.tsx
Add Your First Feature
- Create a new page in app/(dashboard)/your-page/
- Add a new component in components/
- Update the sidebar navigation
Learn the Stack
- Read the complete guide
- Explore the project structure
- Review the features guide
Deploy to Production
- Push to GitHub: git push origin main
- Deploy to Vercel
- See deployment guide for details

📁 Project Structure

my-app/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Auth pages (login, register)
│   ├── (dashboard)/       # Protected dashboard pages
│   ├── api/               # API routes
│   └── ...                # Root pages & layouts
├── components/
│   ├── ui/                # shadcn/ui components (40+)
│   ├── layout/            # Layout components (Sidebar, Topbar)
│   └── ...               # Custom components
├── lib/
│   ├── auth/              # Stack Auth setup
│   ├── db/                # PocketBase client & types
│   ├── email/             # Resend & email templates
│   └── utils.ts           # Shared utilities
├── hooks/                 # Custom React hooks
├── __tests__/             # Unit tests (Jest)
├── tests/e2e/             # E2E tests (Playwright)
└── ...                    # Config files

💻 Available Scripts

# Development
pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm start        # Start production server

# Code Quality
pnpm lint         # Run ESLint
pnpm lint:fix     # Fix ESLint issues
pnpm format       # Format with Prettier
pnpm type-check   # TypeScript type checking

# Testing
pnpm test              # Run unit tests
pnpm test:watch        # Run tests in watch mode
pnpm test:coverage     # Generate coverage report
pnpm test:e2e          # Run E2E tests
pnpm test:e2e:ui       # Run E2E with Playwright UI

🎨 Tech Stack

Frontend

Framework: Next.js 14+ (App Router, React Server Components)
Language: TypeScript (Strict mode)
Styling: Tailwind CSS
Components: shadcn/ui (40+ components)
Icons: Lucide React

Backend & Services

Authentication: Stack Auth (OAuth: Google, GitHub)
Database: PocketBase (SQLite, real-time)
Email: Resend + React Email
Error Tracking: Sentry

Development Tools

Package Manager: pnpm
Linting: ESLint
Formatting: Prettier
Git Hooks: Husky
Commit Linting: Commitlint

Testing

Unit Tests: Jest + @testing-library/react
E2E Tests: Playwright
CI/CD: GitHub Actions

Deployment

Hosting: Vercel (recommended)
Compatible with: Netlify, AWS Amplify, Railway, self-hosted

📚 Documentation

START.md - Complete getting started guide (comprehensive)
dev.md - Development workflow and phase-by-phase implementation
DEPLOYMENT.md - Production deployment guide
POCKETBASE_SETUP.md - Database schema and setup
SENTRY_SETUP.md - Error tracking configuration
REFACTORING.md - Code quality improvements log

🎯 Use Cases

Perfect for building:

✅ SaaS applications
✅ Admin dashboards
✅ Internal tools
✅ MVPs and prototypes
✅ Client projects
✅ Side projects

🚀 What Makes This Different?

🎁 Truly Production-Ready

Not just a boilerplate - includes authentication, database, email, error tracking, testing, and CI/CD out of the box.

📖 Comprehensive Documentation

Over 5 detailed guides covering every aspect from setup to deployment.

🔒 Security First

XSS protection
CSRF tokens
Security headers configured
Environment variable validation
No exposed secrets

⚡ Performance Optimized

SWC minification
Image optimization
Code splitting
Tree shaking
Lazy loading

🧪 Testing Built-In

9 unit tests included
E2E test examples
GitHub Actions CI/CD
Pre-commit hooks

🎨 Best Practices

TypeScript strict mode
Conventional commits
Code quality tools
Consistent structure
Clean, maintainable code

🛠️ Customization

This template is designed to be easily customizable:

Change Branding

Update app name in app/layout.tsx
Modify colors in app/globals.css
Replace logo in public/ and components/layout/sidebar.tsx

Add New Pages

Create route in app/(dashboard)/your-page/
Add to sidebar in components/layout/sidebar.tsx

Modify Database

Update schema in PocketBase admin
Add types in lib/db/types.ts
Create helper functions in lib/db/

Add Components

npx shadcn@latest add [component-name]

More details: See START.md

🐛 Known Issues & Solutions

Build Warnings

OpenTelemetry warnings from Sentry are expected and don't affect functionality

Environment Variables

Client-side variables must be prefixed with NEXT_PUBLIC_
Restart dev server after changing .env.local

More troubleshooting: See START.md

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit using conventional commits (feat:, fix:, docs:, etc.)
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Convention

This project follows Conventional Commits:

feat: add new feature
fix: resolve bug
docs: update documentation
style: code formatting
refactor: code refactoring
test: add/update tests
chore: maintenance tasks

📈 Roadmap

Have a suggestion? Open an issue

📄 License

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

You're free to use this template for personal or commercial projects.

🙏 Acknowledgments

Built with amazing open-source technologies:

Next.js by Vercel
shadcn/ui by @shadcn
Stack Auth
PocketBase
Sentry
Resend
And many more...

💬 Support

📖 Documentation: See START.md for comprehensive guide
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

⭐ Show Your Support

If this template helped you build something awesome, please ⭐ star this repository!

It helps others discover the project and motivates continued development.

Built with ❤️ using Next.js and TypeScript

Get Started • View Demo • Report Bug

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.husky		.husky
__tests__		__tests__
app		app
components		components
config		config
hooks		hooks
lib		lib
public		public
tests		tests
.env.local.example		.env.local.example
.env.production.example		.env.production.example
.env.staging.example		.env.staging.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AUTH_SETUP.md		AUTH_SETUP.md
DEPLOYMENT.md		DEPLOYMENT.md
POCKETBASE_SETUP.md		POCKETBASE_SETUP.md
README.md		README.md
REFACTORING.md		REFACTORING.md
SENTRY_SETUP.md		SENTRY_SETUP.md
START.md		START.md
commitlint.config.js		commitlint.config.js
components.json		components.json
dev.md		dev.md
instrumentation.ts		instrumentation.ts
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
middleware.ts		middleware.ts
next.config.js		next.config.js
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
sentry.client.config.ts		sentry.client.config.ts
sentry.edge.config.ts		sentry.edge.config.ts
sentry.server.config.ts		sentry.server.config.ts
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation