Next.js Full-Stack Template

A modern, production-ready Next.js template with a complete tech stack for building scalable web applications.

🚀 Tech Stack

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: shadcn/ui
• State Management: Zustand
• Data Fetching: TanStack Query (React Query)
• Database: Firebase Firestore
• Authentication: Firebase Auth
• Logging: Custom logger utility
• Error Handling: Global error boundary and logging
• Linting: ESLint with Next.js config
• Package Manager: Bun (recommended)

📋 Features

• ✅ Modern React 19 with Next.js 15
• ✅ TypeScript for type safety
• ✅ Zustand for lightweight state management
• ✅ TanStack Query for server state management
• ✅ shadcn/ui components with Tailwind CSS
• ✅ Firebase integration (Firestore + Auth)
• ✅ Custom logger with different log levels
• ✅ Error boundary for graceful error handling
• ✅ ESLint configuration for code quality
• ✅ Turbopack for faster builds and dev server

🛠️ Getting Started

Prerequisites

• Node.js 18.17 or later
• Bun (recommended) or npm/yarn/pnpm

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd nextjs-template

2. Install dependencies

   bun install
   # or
   npm install

3. Set up environment variables

   Create a .env.local file in the root directory:

   # Firebase Configuration
   NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
   NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
   NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
   NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
   NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
   NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
   
   # Optional: Firebase Admin SDK (for server-side operations)
   FIREBASE_ADMIN_PRIVATE_KEY=your_private_key
   FIREBASE_ADMIN_CLIENT_EMAIL=your_client_email
   
   # Logging Configuration
   NEXT_PUBLIC_LOG_LEVEL=development

4. Set up Firebase

   • Create a new Firebase project at Firebase Console
   • Enable Firestore Database
   • Enable Authentication with your preferred providers
   • Copy your Firebase config to the environment variables

5. Run the development server

   bun dev
   # or
   npm run dev

   Open http://localhost:3000 to see your application.

📁 Project Structure

src/
├── app/
│   ├── (auth)/             # Group for authentication routes
│   │   ├── login/
│   │   │   └── page.tsx
│   │   └── signup/
│   │       └── page.tsx
│   ├── (main)/             # Group for the main app pages
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   ├── settings/
│   │   │   └── page.tsx
│   │   └── layout.tsx      # Shared layout for main app
│   ├── api/                # API routes
│   │   └── ...
│   ├── globals.css         # Global styles
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Homepage
├── components/
│   ├── ui/                 # Small, reusable, "dumb" UI components
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   └── card.tsx
│   └── features/           # More complex components, specific to a feature
│       ├── auth-form.tsx
│       └── project-list.tsx
├── lib/
│   ├── firebase.ts         # Firebase configuration and setup
│   ├── logger.ts           # Custom logger utility
│   ├── utils.ts            # General utility functions (e.g., formatting)
│   └── validations.ts      # Form validation schemas
├── store/                  # Zustand store configuration
│   ├── auth-store.ts       # Authentication state store
│   └── ui-store.ts         # UI state store (modals, notifications, etc.)
├── hooks/
│   ├── use-auth.ts         # Authentication hook
│   ├── use-firestore.ts    # Firestore operations hook
│   └── use-current-user.ts # Example custom hook
├── types/
│   └── index.ts            # Centralized TypeScript types
└── styles/                 # Additional stylesheets
public/
├── favicon.ico
├── file.svg
├── globe.svg
├── next.svg
├── vercel.svg
└── window.svg

🔧 Configuration Details

Zustand Store

Zustand provides lightweight state management with minimal boilerplate:

• Auth Store: User authentication state and actions
• UI Store: Global UI state (modals, notifications, theme, etc.)
• TypeScript: Full type safety with TypeScript
• Persistence: Optional localStorage persistence with zustand/middleware
• DevTools: Integration with Redux DevTools for debugging

TanStack Query

Configured for:

• Caching: Intelligent caching of server data
• Background refetching: Automatic data synchronization
• Error handling: Built-in error states
• Optimistic updates: For better UX

Firebase Integration

• Firestore: NoSQL database for data storage
• Authentication: User authentication with multiple providers
• Security Rules: Configured for secure data access
• Real-time updates: Live data synchronization

Logger Utility

A custom logger with different levels:

• logger.info() - General information
• logger.warn() - Warnings
• logger.error() - Errors
• logger.debug() - Debug information (development only)

Error Handling

• Global Error Boundary: Catches and logs JavaScript errors
• API Error Handling: Standardized error responses
• User-friendly Messages: Graceful error display to users

🎨 UI Components

This template uses shadcn/ui components. To add new components:

bunx shadcn@latest add button
bunx shadcn@latest add card
bunx shadcn@latest add input
# etc.

📝 Scripts

• bun dev - Start development server with Turbopack
• bun build - Build for production
• bun start - Start production server
• bun lint - Run ESLint
• bun lint:fix - Fix ESLint errors automatically

🚀 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Connect your repository to Vercel
3. Add your environment variables in Vercel dashboard
4. Deploy!

Other Platforms

This template works with any platform that supports Next.js:

• Netlify
• Railway
• Digital Ocean
• AWS Amplify

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📚 Learn More

Next.js Resources

• Next.js Documentation
• Learn Next.js

Additional Resources

• Zustand Documentation
• TanStack Query Documentation
• shadcn/ui Components
• Firebase Documentation
• Tailwind CSS Documentation

📄 License

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

---

Happy coding! 🎉