https://github.com/aceiny/nextjs-starter-kit
A modern Next.js starter kit with flexible, reusable, and schema-validated forms featuring built-in error handling. Includes API clients, React Query, Zustand state management, toast notifications, centralized paths/messages, and a clear folder structure , Production-ready and developer-friendly.
https://github.com/aceiny/nextjs-starter-kit
axios nextjs nodejs react-hook-form reactjs reactquery sonner toast-notifications zustand
Last synced: about 1 month ago
JSON representation
A modern Next.js starter kit with flexible, reusable, and schema-validated forms featuring built-in error handling. Includes API clients, React Query, Zustand state management, toast notifications, centralized paths/messages, and a clear folder structure , Production-ready and developer-friendly.
- Host: GitHub
- URL: https://github.com/aceiny/nextjs-starter-kit
- Owner: aceiny
- Created: 2025-11-20T22:03:41.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-11-20T23:06:24.000Z (about 1 month ago)
- Last Synced: 2025-11-21T00:19:47.096Z (about 1 month ago)
- Topics: axios, nextjs, nodejs, react-hook-form, reactjs, reactquery, sonner, toast-notifications, zustand
- Language: TypeScript
- Homepage: https://next-js-starter-kit-qztr.vercel.app/
- Size: 211 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🚀 Next.js Production-Ready Starter
A comprehensive, production-ready Next.js 16 starter template with TypeScript, featuring a complete form system, state management, API clients, and dark mode support.
[](https://nextjs.org/)
[](https://www.typescriptlang.org/)
[](https://react.dev/)
[](LICENSE)
---
## 🧹 Fresh Start - Cleanup Script
If you want to start with a clean slate, delete all documentation and examples:
```bash
npm run cleanup
```
Or directly with bash:
```bash
bash scripts/cleanup.sh
```
This script will:
- ❌ Delete `/docs` directory
- ❌ Delete `/examples` directory
- ✏️ Reset `app/page.tsx` to a minimal home page
- ✏️ Reset `README.md` to a basic template
**Note:** This action is tracked by Git, so you can undo with `git checkout .`
---
## 📋 Table of Contents
- [Features](#-features)
- [Tech Stack](#-tech-stack)
- [Getting Started](#-getting-started)
- [Project Structure](#-project-structure)
- [Documentation](#-documentation)
- [Examples](#-examples)
- [For Developers](#-for-developers)
- [Contributing](#-contributing)
- [License](#-license)
---
## ✨ Features
### 🎨 **UI & Theming**
- ✅ **Dark Mode Support** - Seamless theme switching with `next-themes`
- ✅ **Tailwind CSS v4** - Modern utility-first styling
- ✅ **shadcn/ui Integration** - Beautiful, accessible components
- ✅ **Responsive Design** - Mobile-first approach
- ✅ **Theme Toggle Component** - Multiple variants (slide & click-small)
### 📝 **Form System**
- ✅ **React Hook Form** - Performant form validation
- ✅ **13 Pre-built Components** - Input, Select, Upload, Checkbox, Radio, OTP, etc.
- ✅ **Shadcn-style OTP** - Individual character input boxes
- ✅ **Auto-floating Labels** - Smart label behavior
- ✅ **Password Toggle** - Built-in visibility control
- ✅ **Theme Support** - All components support light/dark themes
### 🎯 **Modal/Dialog System**
- ✅ **useDialog Hook** - Complete dialog state management (recommended)
- ✅ **DialogCreator Component** - Direct component usage for simple dialogs
- ✅ **Per-Button Loading** - Individual loading states for each button
- ✅ **Async Handlers** - Automatic loading during async operations
- ✅ **Three Button Types** - Cancel, Middle (optional), and Action buttons
- ✅ **Button Variants** - Multiple styles (default, destructive, outline, secondary, ghost)
- ✅ **Size Options** - Small, Medium, Large, Extra Large dialogs
- ✅ **Form Support** - Built-in custom form integration
- ✅ **TypeScript Support** - Full type safety with complete interfaces
### 🗄️ **State Management**
- ✅ **Zustand** - Lightweight state management
- ✅ **React Query (TanStack)** - Server state & caching
- ✅ **Persistent Storage** - Auto-save to localStorage
- ✅ **Pre-configured Stores** - Auth & UI stores ready to use
### 🌐 **API Integration**
- ✅ **Axios Clients** - Separate internal & external API clients
- ✅ **Request/Response Interceptors** - Auto-error handling
- ✅ **Cookie Support** - Session management ready
- ✅ **TypeScript Types** - Full type safety
### 🎯 **Developer Experience**
- ✅ **TypeScript** - Full type safety throughout
- ✅ **Path Constants** - Centralized route management
- ✅ **Toast Notifications** - Beautiful Sonner toasts
- ✅ **Comprehensive Docs** - Complete documentation for all features
- ✅ **Example Page** - Live examples of forms & toasts
---
## 🛠️ Tech Stack
| Technology | Purpose | Version |
| ------------------- | ------------------- | ------- |
| **Next.js** | React framework | 16.0.3 |
| **React** | UI library | 19.2.0 |
| **TypeScript** | Type safety | 5.0 |
| **Tailwind CSS** | Styling | 4.0 |
| **React Hook Form** | Form management | 7.66.1 |
| **Zustand** | State management | 5.0.8 |
| **TanStack Query** | Server state | 5.90.10 |
| **Axios** | HTTP client | 1.13.2 |
| **Zod** | Schema validation | 4.1.12 |
| **Sonner** | Toast notifications | 2.0.7 |
| **next-themes** | Theme management | 0.4.6 |
| **shadcn/ui** | Component library | Latest |
| **Lucide React** | Icons | 0.554.0 |
---
## 🚀 Getting Started
### Prerequisites
- **Node.js** 20+ and npm/yarn/pnpm
- **Git** for version control
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/your-username/your-repo-name.git
cd your-repo-name
# or
pnpm dev
```
2. **Install dependencies**
```bash
npm install
# or
yarn install
# or
pnpm install
```
3. **Set up environment variables**
Create a `.env.local` file in the root directory:
```bash
# External API Base URL (required)
API_URL=https://api.example.com # require for the app to run if u dont have one use a fake one to run the app or remove its use from next.config.ts
# External API Base URL (optional)
NEXT_PUBLIC_EXTERNAL_API_URL=https://api.yourdomain.com
# Add other environment variables as needed
```
4. **Run the development server**
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```
5. **Open your browser**
Navigate to [http://localhost:3000](http://localhost:3000) to see your application.
---
## 📁 Project Structure
```
├── app/ # Next.js app directory
│ ├── layout.tsx # Root layout with providers
│ ├── page.tsx # Home page
│ ├── example/ # Example page with forms & toasts
│ └── globals.css # Global styles
│
├── components/
│ ├── form/ # React Hook Form components
│ │ ├── RHFUniversalInput.tsx # Universal input (text, password, OTP, etc.)
│ │ ├── RHFSelect.tsx # Select dropdown
│ │ ├── RHFUpload.tsx # File upload
│ │ ├── RHFCheckbox.tsx # Single checkbox
│ │ ├── RHFCheckboxGroup.tsx # Multiple checkboxes
│ │ ├── RHFSearchableCheckboxGroup.tsx
│ │ ├── RHFRadioGroup.tsx # Radio buttons
│ │ └── ... # Other form components
│ │
│ ├── ui/ # shadcn/ui components
│ │ ├── button.tsx
│ │ ├── input.tsx
│ │ ├── select.tsx
│ │ ├── sonner.tsx # Toast component
│ │ └── ...
│ │
│ └── ThemeToggle.tsx # Dark mode toggle
│
├── stores/ # Zustand stores
│ ├── auth.store.ts # Authentication state
│ ├── ui.store.ts # UI state (sidebar, modal, notifications)
│ └── index.ts # Central export
│
├── lib/
│ ├── http/
│ │ ├── internal-api.ts # Internal API client (Next.js routes)
│ │ └── external-api.ts # External API client
│ │
│ ├── utils/
│ │ └── error.utils.ts # Error extraction utilities
│ │
│ ├── query-client.ts # React Query client
│ └── utils.ts # General utilities
│
├── providers/
│ ├── react-query.provider.tsx # React Query provider
│ └── theme.provider.tsx # Theme provider
│
├── shared/
│ └── constants/
│ ├── paths.ts # Centralized route paths
│ └── toast-messages.ts # Toast message constants
│
├── schema/
│ └── auth.schema.ts # Zod validation schemas
│
├── types/
│ └── index.ts # TypeScript type definitions
│
├── config/
│ └── query.client.config.ts # React Query configuration
│
└── docs/ # Comprehensive documentation
├── FORM_SYSTEM_DOCUMENTATION.md
├── MODAL_DIALOG_DOCUMENTATION.md
├── API_DOCUMENTATION.md
└── STATE_AND_UTILITIES.md
```
---
## 📚 Documentation
Comprehensive guides for all features:
| Documentation | Description | Link |
| --------------------- | -------------------------------------------------------------------------- | ------------------------------------------------- |
| **Form System** | Complete guide to all 13 form components, input types, validation, theming | [View Docs](./docs/FORM_SYSTEM_DOCUMENTATION.md) |
| **Modal/Dialog** | Dialog system with per-button loading, async handlers, and customization | [View Docs](./docs/MODAL_DIALOG_DOCUMENTATION.md) |
| **API & Axios** | HTTP clients setup, interceptors, error handling, authentication | [View Docs](./docs/API_DOCUMENTATION.md) |
| **State & Utilities** | Zustand stores, React Query, Toasts, Path constants | [View Docs](./docs/STATE_AND_UTILITIES.md) |
### Quick Links
- **🎨 Form Components** - [Form System Documentation](./docs/FORM_SYSTEM_DOCUMENTATION.md)
- **🎯 Modal/Dialog** - [Modal & Dialog Documentation](./docs/MODAL_DIALOG_DOCUMENTATION.md)
- **🌐 API Calls** - [API Documentation](./docs/API_DOCUMENTATION.md)
- **🗄️ State Management** - [State & Utilities Documentation](./docs/STATE_AND_UTILITIES.md)
---
## 🎯 Examples
### Live Examples
Visit the **[/example](http://localhost:3000/example)** page to see:
- ✅ **All Form Components** in action
- Text inputs with auto-floating labels
- Password inputs with visibility toggle
- Shadcn-style OTP with individual character boxes
- File uploads (default, avatar, button styles)
- Select dropdowns (single & multi-select)
- Checkboxes & radio groups
- Date & time pickers
- ✅ **Toast Notifications**
- Success, error, info, warning toasts
- Promise-based toasts for async operations
- Custom toast messages
- ✅ **Dark Mode Toggle**
- Seamless theme switching
- All components support both themes
### Code Examples
#### Authentication with Zustand
```tsx
import { useAuthStore } from "@/stores";
import { internalAPI } from "@/lib/http/internal-api";
import { toast } from "sonner";
function LoginForm() {
const { login } = useAuthStore();
async function handleLogin(data: LoginDto) {
try {
const response = await internalAPI.post("/auth/login", data);
login(response.data.user);
toast.success("Login successful!");
} catch (error) {
toast.error(error);
}
}
return ...;
}
```
#### Data Fetching with React Query
```tsx
import { useQuery } from "@tanstack/react-query";
import { internalAPI } from "@/lib/http/internal-api";
function UserList() {
const { data: users, isLoading } = useQuery({
queryKey: ["users"],
queryFn: async () => {
const response = await internalAPI.get("/users");
return response.data;
},
});
if (isLoading) return
Loading...;
return (
{users.map((user) => (
))}
);
}
```
#### Form with Validation
```tsx
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { RHFUniversalInput } from "@/components/form";
import { loginSchema } from "@/schema/auth.schema";
function LoginForm() {
const { control, handleSubmit } = useForm({
resolver: zodResolver(loginSchema),
});
return (
Login
);
}
```
#### Modal/Dialog Management
```tsx
import { useDialog } from "@/hooks/useDialog";
import { toast } from "sonner";
function UserManagement() {
const deleteDialog = useDialog({
title: "Delete User",
subtitle: "This action cannot be undone.",
size: "md",
cancelButton: {
label: "Cancel",
},
actionButton: {
label: "Delete",
variant: "destructive",
onClick: async () => {
try {
await internalAPI.delete(`/users/${userId}`);
toast.success("User deleted successfully");
} catch (error) {
toast.error("Failed to delete user");
}
},
},
});
return (
Delete User
{deleteDialog.dialog}
);
}
```
**Features:**
- ✅ Automatic loading state during async operations
- ✅ Per-button loading control
- ✅ Type-safe dialog configuration
- ✅ Easy to override config when opening
- ✅ Built-in form support
- ✅ Multiple button variants
**[→ Full Modal Documentation](./docs/MODAL_DIALOG_DOCUMENTATION.md)**
---
## 👨💻 For Developers
### Development Workflow
1. **Start development server**
```bash
npm run dev
```
2. **View example page**
- Navigate to [http://localhost:3000/example](http://localhost:3000/example)
- See all form components and toasts in action
3. **Read the documentation**
- [Form System](./docs/FORM_SYSTEM_DOCUMENTATION.md) - Learn about all form components
- [API Integration](./docs/API_DOCUMENTATION.md) - Set up API calls
- [State Management](./docs/STATE_AND_UTILITIES.md) - Use Zustand & React Query
4. **Build your features**
- Use pre-built components
- Follow the established patterns
- Refer to examples in `/example`
### Available Scripts
```bash
# Development
npm run dev # Start dev server
# Production
npm run build # Build for production
npm run start # Start production server
# Code Quality
npm run lint # Run ESLint
```
### Adding New Features
#### Create a New Page
```tsx
// app/dashboard/page.tsx
export default function DashboardPage() {
return
Dashboard;
}
```
#### Create a New API Service
```typescript
// lib/services/post.service.ts
import { internalAPI } from "@/lib/http/internal-api";
export const postService = {
async getAll() {
const response = await internalAPI.get("/posts");
return response.data;
},
// Add more methods...
};
```
#### Create a New Store
```typescript
// stores/post.store.ts
import { create } from "zustand";
export const usePostStore = create((set) => ({
posts: [],
setPosts: (posts) => set({ posts }),
}));
```
#### Add New Path Constants
```typescript
// shared/constants/paths.ts
export const APP_PATHS = {
// ... existing paths
DASHBOARD: "/dashboard",
SETTINGS: "/settings",
};
```
---
## 🎨 Theme Toggle Component
The `ThemeToggle` component provides flexible theme switching with multiple variants.
### Basic Usage
```tsx
import { ThemeToggle } from "@/components/ThemeToggle";
export default function Header() {
return (
);
}
```
### Variants
#### Click-Small (Default)
```tsx
```
- Compact button design
- Perfect for headers/navigation
- Single click to toggle theme
#### Slide
```tsx
```
- Animated slide switch design
- More prominent visual feedback
- Great for settings pages
### Props
| Prop | Type | Default | Description |
| --------- | -------------------------- | --------------- | ------------------ |
| `variant` | `"slide" \| "click-small"` | `"click-small"` | Theme toggle style |
### How It Works
1. Uses `next-themes` for theme management
2. Syncs across all browser tabs
3. Persists theme preference to localStorage
4. Respects system theme preference on first visit
5. Hydration-safe (prevents hydration mismatch)
### Theme-Aware Components
All form components automatically respond to theme changes:
- Text inputs, selects, textareas
- OTP input boxes
- File uploads
- Checkboxes and radio groups
- Labels and error messages
- Editor with syntax highlighting on links
### Customizing Themes
Edit your Tailwind config to customize light/dark mode colors:
```javascript
// tailwind.config.js
export default {
darkMode: "class",
theme: {
extend: {
colors: {
// Custom colors for light mode
// Custom colors for dark mode
},
},
},
};
```
### Programmatic Theme Control
```tsx
import { useTheme } from "next-themes";
export function ThemeController() {
const { theme, setTheme } = useTheme();
return (
Current theme: {theme}
setTheme("light")}>Light
setTheme("dark")}>Dark
);
}
```
---
## 🤝 Contributing
Contributions are welcome! If you'd like to improve this starter template:
1. **Fork the repository**
2. **Create a 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 Documentation](https://nextjs.org/docs)
- [React Hook Form](https://react-hook-form.com/)
- [Zustand](https://docs.pmnd.rs/zustand/getting-started/introduction)
- [TanStack Query](https://tanstack.com/query/latest)
- [Tailwind CSS](https://tailwindcss.com/docs)
- [shadcn/ui](https://ui.shadcn.com/)
---
## ⭐ Star This Project
If you find this starter helpful, please consider giving it a star on GitHub! It helps others discover this template.
**[⭐ Star on GitHub](https://github.com/aceiny/NextJs-Starter-Kit)**
---
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## 🙏 Acknowledgments
- **Next.js Team** - For the amazing framework
- **shadcn** - For the beautiful component library
- **TanStack** - For React Query
- **Sonner** - For beautiful toasts
---
**Built with ❤️ by developers, for developers**
**Ready to start building?** [View Examples →](http://localhost:3000/example)