Next.js Invoice Dashboard

A modern, full-stack invoice and customer management dashboard built with Next.js 16, React 19, and TypeScript. Manage customers, create and track invoices, and monitor revenue with a clean, responsive UI powered by Tailwind CSS.

🚀 Features

• Dashboard Overview - Real-time revenue charts and latest invoices at a glance
• Customer Management - View, search, and manage all customers
• Invoice Management - Create, edit, view, and delete invoices
• Authentication - Secure login with NextAuth.js
• Responsive Design - Mobile-friendly interface with Tailwind CSS
• Search & Filtering - Fast, debounced search across customers and invoices
• Pagination - Efficient data pagination for large datasets
• Status Tracking - Track invoice status (pending/paid) with visual indicators
• Type-Safe - Full TypeScript support for reliability
• Database - PostgreSQL integration for persistent data storage

📋 Tech Stack

Technology	Version	Purpose
Next.js	^16.0.10	React framework with App Router
React	^19.2.0	UI library
TypeScript	^6.0.2	Type safety
Tailwind CSS	3.4.17	Styling
NextAuth.js	5.0.0-beta.25	Authentication
PostgreSQL	^3.4.6	Database
Zod	^3.25.17	Schema validation
bcryptjs	^2.4.3	Password hashing
Heroicons	^2.2.0	UI icons

🛠️ Installation

Prerequisites

• Node.js 18+
• pnpm (or npm/yarn)
• PostgreSQL database

Setup Steps

1. Clone the repository

   git clone <repository-url>
   cd nextjs-dashboard

2. Install dependencies

   pnpm install

3. Set up environment variables Create a .env.local file in the root directory:

   DATABASE_URL=postgresql://user:password@localhost:5432/dashboard
   NEXTAUTH_SECRET=your-secret-key-here
   NEXTAUTH_URL=http://localhost:3000

4. Set up the database

   # Run seed script to populate sample data
   pnpm run seed

5. Start the development server

   pnpm dev

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

📖 Usage

Available Scripts

# Development server with Turbopack
pnpm dev

# Production build
pnpm build

# Start production server
pnpm start

# Run linting
pnpm lint

Project Structure

nextjs-dashboard/
├── app/                      # Next.js App Router
│   ├── dashboard/           # Dashboard routes
│   │   ├── customers/       # Customer management
│   │   ├── invoices/        # Invoice management
│   │   └── (overview)/      # Dashboard overview
│   ├── lib/                 # Utilities & data access
│   │   ├── actions.ts       # Server actions
│   │   ├── data.ts          # Database queries
│   │   ├── definitions.ts   # Type definitions
│   │   └── utils.ts         # Helper functions
│   └── ui/                  # React components
│       ├── dashboard/       # Dashboard components
│       └── invoices/        # Invoice components
├── public/                  # Static assets
├── types/                   # TypeScript type definitions
└── tailwind.config.ts       # Tailwind configuration

🔐 Authentication

This project uses NextAuth.js for authentication. Users must log in to access the dashboard.

Default Credentials

The seed script creates a test user:

• Email: user@example.com
• Password: password123

Note: Change these credentials in production!

🗄️ Database Schema

The application manages three main entities:

• Users - Authentication credentials and user info
• Customers - Customer details and contact information
• Invoices - Invoice records with amounts, dates, and status

All data is stored in PostgreSQL with proper indexing for performance.

🎨 UI Components

Key reusable components:

• Button - Customizable button component
• Search - Debounced search input
• Pagination - Data pagination control
• StatusBadge - Invoice status indicator
• Breadcrumbs - Navigation breadcrumbs
• SideNav - Sidebar navigation
• Cards - Dashboard metric cards
• RevenueChart - Revenue visualization
• Table - Data table component

✅ Code Quality

• ESLint - Code linting and quality checks
• TypeScript - Static type checking
• Accessibility - WCAG compliance for UI components

Run linting:

pnpm lint

🐛 Troubleshooting

ESLint Compatibility Issues

If you encounter ESLint errors with eslint-plugin-react, ensure you're using ESLint 9.x (not 10.x) for compatibility with the current eslint-config-next version.

Database Connection Issues

• Verify PostgreSQL is running
• Check DATABASE_URL in .env.local
• Ensure database credentials are correct

Port Already in Use

If port 3000 is busy:

pnpm dev -- -p 3001

📦 Deployment

Deploy to Vercel (Recommended)

1. Push your code to GitHub/GitLab
2. Import the project in Vercel Dashboard
3. Add environment variables
4. Deploy with one click

Deploy to Other Platforms

• Docker - Build a Docker image for containerized deployment
• AWS, GCP, Azure - Use their Node.js hosting options
• Self-hosted - Run on any server with Node.js support

Build for production:

pnpm build
pnpm start

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📄 License

This project is open source and available under the MIT License.

📞 Support

For issues and feature requests, please use the GitHub Issues page.

---

Happy invoicing! 🎉