{"id":33346502,"url":"https://github.com/aceiny/nextjs-starter-kit","last_synced_at":"2026-04-09T18:09:03.068Z","repository":{"id":325363366,"uuid":"1100875970","full_name":"aceiny/NextJs-Starter-Kit","owner":"aceiny","description":"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.","archived":false,"fork":false,"pushed_at":"2025-11-20T23:06:24.000Z","size":216,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-21T00:19:47.096Z","etag":null,"topics":["axios","nextjs","nodejs","react-hook-form","reactjs","reactquery","sonner","toast-notifications","zustand"],"latest_commit_sha":null,"homepage":"https://next-js-starter-kit-qztr.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aceiny.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T22:03:41.000Z","updated_at":"2025-11-20T23:11:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aceiny/NextJs-Starter-Kit","commit_stats":null,"previous_names":["aceiny/nextjs-starter-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aceiny/NextJs-Starter-Kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aceiny%2FNextJs-Starter-Kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aceiny%2FNextJs-Starter-Kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aceiny%2FNextJs-Starter-Kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aceiny%2FNextJs-Starter-Kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aceiny","download_url":"https://codeload.github.com/aceiny/NextJs-Starter-Kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aceiny%2FNextJs-Starter-Kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285748794,"owners_count":27225088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-22T02:00:05.934Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axios","nextjs","nodejs","react-hook-form","reactjs","reactquery","sonner","toast-notifications","zustand"],"created_at":"2025-11-22T07:01:00.501Z","updated_at":"2026-04-09T18:09:03.062Z","avatar_url":"https://github.com/aceiny.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Next.js Production-Ready Starter\n\nA comprehensive, production-ready and scalable Next.js 16 starter template with TypeScript, featuring a complete form system, state management, API clients, and dark mode support.\n\n[![Next.js](https://img.shields.io/badge/Next.js-16.0-black?style=flat\u0026logo=next.js)](https://nextjs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=flat\u0026logo=typescript)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-19.2-61dafb?style=flat\u0026logo=react)](https://react.dev/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n---\n\n## 🧹 Fresh Start - Cleanup Script\n\nIf you want to start with a clean slate, delete all documentation and examples:\n\n```bash\nnpm run cleanup\n```\n\nOr directly with bash:\n\n```bash\nbash scripts/cleanup.sh\n```\n\nThis script will:\n\n- ❌ Delete `/docs` directory\n- ❌ Delete `/examples` directory\n- ❌ Delete `/app/example` directory\n- ✏️ Reset `app/page.tsx` to a minimal home page\n- ✏️ Reset `README.md` to a basic template\n\n**Per-directory/file confirmation:**\nBy default, you will be prompted before each directory or file is deleted (docs, examples, app/example, app/page.tsx, README.md). Confirm with 'y' to proceed or any other key to skip that item.\n\n**Force mode:**\nTo skip all prompts and force cleanup, use:\n\n```bash\nbash scripts/cleanup.sh --force\n# or\nbash scripts/cleanup.sh -f\n```\n\nThis will delete all targeted files and directories without any confirmation.\n\n**Note:** This action is tracked by Git, so you can undo with `git checkout .`\n\n---\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Tech Stack](#-tech-stack)\n- [Getting Started](#-getting-started)\n- [Project Structure](#-project-structure)\n- [Documentation](#-documentation)\n- [Examples](#-examples)\n- [For Developers](#-for-developers)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## ✨ Features\n\n### 🎨 **UI \u0026 Theming**\n\n- ✅ **Dark Mode Support** - Seamless theme switching with `next-themes`\n- ✅ **Tailwind CSS v4** - Modern utility-first styling\n- ✅ **shadcn/ui Integration** - Beautiful, accessible components\n- ✅ **Responsive Design** - Mobile-first approach\n- ✅ **Theme Toggle Component** - Multiple variants (slide \u0026 click-small)\n\n### 📝 **Form System**\n\n- ✅ **React Hook Form** - Performant form validation\n- ✅ **13 Pre-built Components** - Input, Select, Upload, Checkbox, Radio, OTP, etc.\n- ✅ **Shadcn-style OTP** - Individual character input boxes\n- ✅ **Auto-floating Labels** - Smart label behavior\n- ✅ **Password Toggle** - Built-in visibility control\n- ✅ **Theme Support** - All components support light/dark themes\n\n### 🎯 **Modal/Dialog System**\n\n- ✅ **useDialog Hook** - Complete dialog state management (recommended)\n- ✅ **DialogCreator Component** - Direct component usage for simple dialogs\n- ✅ **Per-Button Loading** - Individual loading states for each button\n- ✅ **Async Handlers** - Automatic loading during async operations\n- ✅ **Three Button Types** - Cancel, Middle (optional), and Action buttons\n- ✅ **Button Variants** - Multiple styles (default, destructive, outline, secondary, ghost)\n- ✅ **Ripple-enabled Action Buttons** - `ActionButton` helper and `RippleButton` utility for card/dialog actions\n- ✅ **Size Options** - Small, Medium, Large, Extra Large dialogs\n- ✅ **Form Support** - Built-in custom form integration\n- ✅ **TypeScript Support** - Full type safety with complete interfaces\n\n### 🗄️ **State Management**\n\n- ✅ **Zustand** - Lightweight state management\n- ✅ **React Query (TanStack)** - Server state \u0026 caching\n- ✅ **Persistent Storage** - Auto-save to localStorage\n- ✅ **Pre-configured Stores** - Auth \u0026 UI stores ready to use\n\n### 🌐 **API Integration**\n\n- ✅ **Axios Clients** - Separate internal \u0026 external API clients\n- ✅ **Request/Response Interceptors** - Auto-error handling\n- ✅ **Cookie Support** - Session management ready\n- ✅ **TypeScript Types** - Full type safety\n\n### 📊 **DataTable Component**\n\n- ✅ **Sortable Columns** - Click-to-sort with visual indicators\n- ✅ **Pagination** - Built-in pagination with customizable page sizes\n- ✅ **Row Selection** - Single or multi-select with checkboxes\n- ✅ **Actions Column** - Dropdown actions for each row\n- ✅ **Empty \u0026 Error States** - Beautiful placeholder states\n- ✅ **Loading Skeleton** - Smooth loading experience\n- ✅ **Dark Mode** - Full theme support\n\n### 💬 **Tooltips \u0026 Toasts**\n\n- ✅ **Custom Tooltips** - Variant-based (info, success, warning, error)\n- ✅ **Multiple Sizes** - Small, medium, large options\n- ✅ **Positioning** - Top, bottom, left, right with alignment\n- ✅ **Toast Notifications** - Sonner-powered with promise support\n- ✅ **Pre-configured Messages** - Toast message constants\n\n### 📋 **Dropdown Menus**\n\n- ✅ **ActionMenu Component** - Easy-to-use action dropdowns\n- ✅ **Grouped Items** - Organize actions with labels\n- ✅ **Checkbox \u0026 Radio** - Selection menus\n- ✅ **Submenus** - Nested dropdown support\n- ✅ **Keyboard Shortcuts** - Display shortcut hints\n- ✅ **Destructive Actions** - Visual warning for dangerous actions\n\n### 🔍 **Universal Filters**\n\n- ✅ **13 Filter Types** - Text, select, multi-select, number range, date range, checkbox, radio, search, tags, and more\n- ✅ **URL Synchronization** - Filters sync with URL query params\n- ✅ **Two Display Modes** - Tabs mode or compact dropdown mode\n- ✅ **TypeScript Support** - Fully typed filter configurations\n- ✅ **Debounced Inputs** - Optimized performance for text filters\n- ✅ **Theme Support** - Works seamlessly with dark mode\n\n### 🛡️ **Middleware System**\n\n- ✅ **Middleware Chaining** - Compose multiple middlewares in sequence\n- ✅ **Auth Guard** - Built-in authentication middleware\n- ✅ **Skip Static Assets** - Automatically bypass middleware for static files\n- ✅ **Type-Safe** - Full TypeScript support with custom middleware types\n- ✅ **Easy to Extend** - Simple pattern for creating custom middlewares\n- ✅ **Examples Included** - Logging, rate limiting, security headers, and more\n\n### 🎯 **Developer Experience**\n\n- ✅ **TypeScript** - Full type safety throughout\n- ✅ **Path Constants** - Centralized route management\n- ✅ **Comprehensive Docs** - Complete documentation for all features\n- ✅ **Example Routes** - Organized examples at `/example/*`\n\n---\n\n## 🛠️ Tech Stack\n\n| Technology          | Purpose             | Version |\n| ------------------- | ------------------- | ------- |\n| **Next.js**         | React framework     | 16.0.3  |\n| **React**           | UI library          | 19.2.0  |\n| **TypeScript**      | Type safety         | 5.0     |\n| **Tailwind CSS**    | Styling             | 4.0     |\n| **React Hook Form** | Form management     | 7.66.1  |\n| **Zustand**         | State management    | 5.0.8   |\n| **TanStack Query**  | Server state        | 5.90.10 |\n| **Axios**           | HTTP client         | 1.13.2  |\n| **Zod**             | Schema validation   | 4.1.12  |\n| **Sonner**          | Toast notifications | 2.0.7   |\n| **next-themes**     | Theme management    | 0.4.6   |\n| **shadcn/ui**       | Component library   | Latest  |\n| **Lucide React**    | Icons               | 0.554.0 |\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- **Node.js** 20+ and npm/yarn/pnpm\n- **Git** for version control\n\n### Installation\n\n1. **Clone the repository**\n\n```bash\ngit clone https://github.com/your-username/your-repo-name.git\ncd your-repo-name\n# or\npnpm dev\n```\n\n2. **Install dependencies**\n\n```bash\nnpm install\n# or\nyarn install\n# or\npnpm install\n```\n\n3. **Set up environment variables**\n\nCreate a `.env.local` file in the root directory:\n\n```bash\n# External API Base URL (required)\nAPI_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\n\n# External API Base URL (optional)\nNEXT_PUBLIC_EXTERNAL_API_URL=https://api.yourdomain.com\n\n# Add other environment variables as needed\n```\n\n4. **Run the development server**\n\n```bash\nnpm run dev\n# or\nyarn dev\n# or\npnpm dev\n```\n\n5. **Open your browser**\n\nNavigate to [http://localhost:3000](http://localhost:3000) to see your application.\n\n---\n\n## 📁 Project Structure\n\nThis structure is designed to be scalable, with clear separation of app routes, shared UI, domain features, and configuration.\n\n```\n├── src/\n│   ├── app/                          # Next.js app directory\n│   │   ├── layout.tsx               # Root layout with providers\n│   │   ├── page.tsx                 # Home page\n│   │   ├── example/                 # Example pages\n│   │   │   ├── page.tsx             # Examples navigation hub\n│   │   │   ├── data-table/          # DataTable examples\n│   │   │   ├── dialog/              # Dialog examples\n│   │   │   ├── dropdown/            # Dropdown/ActionMenu examples\n│   │   │   ├── form/                # Form examples\n│   │   │   ├── filters/             # Universal filters examples\n│   │   │   ├── tabs/                # Tabs examples\n│   │   │   └── toast/               # Toast \u0026 Tooltip examples\n│   │   └── globals.css              # Global styles\n│   │\n│   ├── components/\n│   │   ├── common/                  # Feature-focused UI (charts, dialog, dropdown, form, table, etc.)\n│   │   ├── page/                    # Page-level UI components\n│   │   ├── ui/                      # Reusable base UI components\n│   │   └── ThemeToggle.tsx          # Dark mode toggle\n│   │\n│   ├── config/                      # App configuration\n│   │   ├── query.client.config.ts   # React Query configuration\n│   │   └── rhf/                     # React Hook Form defaults\n│   │\n│   ├── hooks/                       # Custom hooks\n│   │   ├── use-dialog.ts\n│   │   └── shared/                  # Shared hooks (debounce, storage, pagination, etc.)\n│   │\n│   ├── lib/                         # Helpers \u0026 utilities\n│   │   ├── http/                    # API clients\n│   │   ├── query-client.ts          # React Query client\n│   │   └── utils.ts                 # General utilities\n│   │\n│   ├── middlewares/                 # Middleware system\n│   │   ├── chain.ts                 # Middleware chaining utility\n│   │   ├── auth-guard.middleware.ts # Authentication middleware\n│   │   └── skip-static.middleware.ts # Skip static assets\n│   │\n│   ├── providers/                   # App providers\n│   │   ├── heroui.provider.tsx\n│   │   ├── react-query.provider.tsx\n│   │   └── theme.provider.tsx\n│   │\n│   ├── schema/                      # Zod validation schemas\n│   │   └── auth.schema.ts\n│   │\n│   ├── section/                     # Page sections grouped by domain\n│   │   ├── auth/\n│   │   └── error/\n│   │\n│   ├── shared/                      # Shared constants and styles\n│   │   ├── constants/\n│   │   └── styles/\n│   │\n│   ├── stores/                      # Zustand stores\n│   │   ├── auth.store.ts\n│   │   ├── ui.store.ts\n│   │   └── index.ts\n│   │\n│   └── types/                       # TypeScript types\n│       ├── index.ts\n│       ├── pagination/\n│       └── shared/\n│\n├── docs/                            # Comprehensive documentation\n├── examples/                        # Example snippets\n├── public/                          # Static assets\n└── scripts/                         # Utility scripts\n```\n\n---\n\n## 📚 Documentation\n\nComprehensive guides for all features:\n\n| Documentation          | Description                                                                       | Link                                                      |\n| ---------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------- |\n| **Form System**        | Complete guide to all 13 form components, input types, validation, theming        | [View Docs](./docs/FORM_SYSTEM_DOCUMENTATION.md)          |\n| **Modal/Dialog**       | Dialog system with per-button loading, async handlers, and customization          | [View Docs](./docs/MODAL_DIALOG_DOCUMENTATION.md)         |\n| **Tooltip \u0026 Dropdown** | CustomTooltip variants, ActionMenu with groups, checkboxes, submenus              | [View Docs](./docs/TOOLTIP_AND_DROPDOWN_DOCUMENTATION.md) |\n| **Middleware System**  | Middleware chaining, auth guard, rate limiting, logging, custom middleware setup  | [View Docs](./docs/MIDDLEWARE_DOCUMENTATION.md)           |\n| **Charts \u0026 Analytics** | Compact ApexCharts-based sparklines and mini-bar charts with dashboard widgets | [View Docs](./docs/CHARTS_AND_ANALYTICS.md) |\n| **API \u0026 Axios**        | HTTP clients setup, interceptors, error handling, authentication                  | [View Docs](./docs/API_DOCUMENTATION.md)                  |\n| **State \u0026 Utilities**  | Zustand stores, React Query, Toasts, Path constants                               | [View Docs](./docs/STATE_AND_UTILITIES.md)                |\n| **Universal Filters**  | 13 filter types with URL sync, tabs/dropdown modes, TypeScript examples           | [View Docs](./docs/UNIVERSAL_FILTERS_DOCUMENTATION.md)    |\n| **DataTable**          | Sortable, paginated data tables with selection and actions                        | [View Docs](./docs/DATA_TABLE_DOCUMENTATION.md)           |\n\n## Custom React Hooks\n\n### useLocalStorage\n\nPersist and sync state with localStorage. Supports SSR, override, and cross-tab updates.\n\n```ts\nconst [value, setValue, removeValue] = useLocalStorage\u003cstring\u003e(\n  \"key\",\n  \"default\",\n);\n```\n\n### useSessionStorage\n\nPersist and sync state with sessionStorage. Includes utility functions for direct access.\n\n```ts\nconst [value, setValue, removeValue] = useSessionStorage\u003cnumber\u003e(\"key\", 0);\n```\n\n### useDebounce\n\nDebounce any value or state change for smoother UX and reduced API calls.\n\n```ts\nconst debounced = useDebounce(searchTerm, 300);\n```\n\n### usePagination\n\nUniversal pagination for server/client-side. Syncs with URL query params and exposes config.\n\n```ts\nconst { pageIndex, pageSize, pagination } = usePagination();\n```\n\n### Quick Links\n\n- **🎨 Form Components** - [Form System Documentation](./docs/FORM_SYSTEM_DOCUMENTATION.md)\n- **🎯 Modal/Dialog** - [Modal \u0026 Dialog Documentation](./docs/MODAL_DIALOG_DOCUMENTATION.md)\n- **💬 Tooltips \u0026 Dropdowns** - [Tooltip \u0026 Dropdown Documentation](./docs/TOOLTIP_AND_DROPDOWN_DOCUMENTATION.md)\n- **🛡️ Middleware System** - [Middleware Documentation](./docs/MIDDLEWARE_DOCUMENTATION.md)\n- **🌐 API Calls** - [API Documentation](./docs/API_DOCUMENTATION.md)\n- **🗄️ State Management** - [State \u0026 Utilities Documentation](./docs/STATE_AND_UTILITIES.md)\n\n---\n\n## 🎯 Examples\n\n### Live Examples\n\nVisit the **[/example](http://localhost:3000/example)** page for the examples hub, with links to:\n\n| Route                                                               | Description                                            |\n| ------------------------------------------------------------------- | ------------------------------------------------------ |\n| **[/example/data-table](http://localhost:3000/example/data-table)** | DataTable with sorting, selection, actions, pagination |\n| **[/example/dialog](http://localhost:3000/example/dialog)**         | Modal dialogs with async handlers \u0026 per-button loading |\n| **[/example/dropdown](http://localhost:3000/example/dropdown)**     | ActionMenu with groups, checkboxes, radios, submenus   |\n| **[/example/form](http://localhost:3000/example/form)**             | All form components - inputs, selects, uploads, OTP    |\n| **[/example/toast](http://localhost:3000/example/toast)**           | Sonner toasts \u0026 custom tooltips with variants          |\n| **[/example/filters](http://localhost:3000/example/filters)**       | Universal filters with URL sync, 13 filter types       |\n\n### Feature Highlights\n\n- ✅ **DataTable** - Sorting, pagination, row selection, actions column\n- ✅ **Tooltips** - Info, success, warning, error variants with sizes\n- ✅ **Dropdown Menus** - Groups, checkboxes, radios, keyboard shortcuts\n- ✅ **Form Components** - Floating labels, OTP, file uploads, validation\n- ✅ **Toast Notifications** - Promise-based, multiple types\n- ✅ **Dark Mode** - All components support both themes\n\n### Code Examples\n\n#### Authentication with Zustand\n\n```tsx\nimport { useAuthStore } from \"@/stores\";\nimport { internalAPI } from \"@/lib/http/internal-api\";\nimport { toast } from \"sonner\";\n\nfunction LoginForm() {\n  const { login } = useAuthStore();\n\n  async function handleLogin(data: LoginDto) {\n    try {\n      const response = await internalAPI.post(\"/auth/login\", data);\n      login(response.data.user);\n      toast.success(\"Login successful!\");\n    } catch (error) {\n      toast.error(error);\n    }\n  }\n\n  return \u003cform onSubmit={handleLogin}\u003e...\u003c/form\u003e;\n}\n```\n\n#### Data Fetching with React Query\n\n```tsx\nimport { useQuery } from \"@tanstack/react-query\";\nimport { internalAPI } from \"@/lib/http/internal-api\";\n\nfunction UserList() {\n  const { data: users, isLoading } = useQuery({\n    queryKey: [\"users\"],\n    queryFn: async () =\u003e {\n      const response = await internalAPI.get(\"/users\");\n      return response.data;\n    },\n  });\n\n  if (isLoading) return \u003cdiv\u003eLoading...\u003c/div\u003e;\n  return (\n    \u003cdiv\u003e\n      {users.map((user) =\u003e (\n        \u003cUserCard user={user} /\u003e\n      ))}\n    \u003c/div\u003e\n  );\n}\n```\n\n#### Form with Validation\n\n```tsx\nimport { useForm } from \"react-hook-form\";\nimport { zodResolver } from \"@hookform/resolvers/zod\";\nimport { RHFUniversalInput } from \"@/components/form\";\nimport { loginSchema } from \"@/schema/auth.schema\";\n\nfunction LoginForm() {\n  const { control, handleSubmit } = useForm({\n    resolver: zodResolver(loginSchema),\n  });\n\n  return (\n    \u003cform onSubmit={handleSubmit(onSubmit)}\u003e\n      \u003cRHFUniversalInput\n        control={control}\n        name=\"email\"\n        type=\"email\"\n        label=\"Email\"\n        placeholder=\"Enter your email\"\n      /\u003e\n      \u003cRHFUniversalInput\n        control={control}\n        name=\"password\"\n        type=\"password\"\n        label=\"Password\"\n        showPasswordToggle\n      /\u003e\n      \u003cbutton type=\"submit\"\u003eLogin\u003c/button\u003e\n    \u003c/form\u003e\n  );\n}\n```\n\n#### Modal/Dialog Management\n\n```tsx\nimport { useDialog } from \"@/hooks/useDialog\";\nimport { toast } from \"sonner\";\n\nfunction UserManagement() {\n  const deleteDialog = useDialog({\n    title: \"Delete User\",\n    subtitle: \"This action cannot be undone.\",\n    size: \"md\",\n    cancelButton: {\n      label: \"Cancel\",\n    },\n    actionButton: {\n      label: \"Delete\",\n      variant: \"destructive\",\n      onClick: async () =\u003e {\n        try {\n          await internalAPI.delete(`/users/${userId}`);\n          toast.success(\"User deleted successfully\");\n        } catch (error) {\n          toast.error(\"Failed to delete user\");\n        }\n      },\n    },\n  });\n\n  return (\n    \u003cdiv\u003e\n      \u003cbutton onClick={deleteDialog.openDialog} className=\"text-red-600\"\u003e\n        Delete User\n      \u003c/button\u003e\n      {deleteDialog.dialog}\n    \u003c/div\u003e\n  );\n}\n```\n\n**Features:**\n\n- ✅ Automatic loading state during async operations\n- ✅ Per-button loading control\n- ✅ Type-safe dialog configuration\n- ✅ Easy to override config when opening\n- ✅ Built-in form support\n- ✅ Multiple button variants\n\n**[→ Full Modal Documentation](./docs/MODAL_DIALOG_DOCUMENTATION.md)**\n\n---\n\n## 👨‍💻 For Developers\n\n### Development Workflow\n\n1. **Start development server**\n\n   ```bash\n   npm run dev\n   ```\n\n2. **View example page**\n   - Navigate to [http://localhost:3000/example](http://localhost:3000/example)\n   - See all form components and toasts in action\n\n3. **Read the documentation**\n   - [Form System](./docs/FORM_SYSTEM_DOCUMENTATION.md) - Learn about all form components\n   - [API Integration](./docs/API_DOCUMENTATION.md) - Set up API calls\n   - [State Management](./docs/STATE_AND_UTILITIES.md) - Use Zustand \u0026 React Query\n\n4. **Build your features**\n   - Use pre-built components\n   - Follow the established patterns\n   - Refer to examples in `/example`\n\n### Available Scripts\n\n```bash\n# Development\nnpm run dev          # Start dev server\n\n# Production\nnpm run build        # Build for production\nnpm run start        # Start production server\n\n# Code Quality\nnpm run lint         # Run ESLint\n```\n\n### Adding New Features\n\n#### Create a New Page\n\n```tsx\n// app/dashboard/page.tsx\nexport default function DashboardPage() {\n  return \u003cdiv\u003eDashboard\u003c/div\u003e;\n}\n```\n\n#### Create a New API Service\n\n```typescript\n// lib/services/post.service.ts\nimport { internalAPI } from \"@/lib/http/internal-api\";\n\nexport const postService = {\n  async getAll() {\n    const response = await internalAPI.get(\"/posts\");\n    return response.data;\n  },\n  // Add more methods...\n};\n```\n\n#### Create a New Store\n\n```typescript\n// stores/post.store.ts\nimport { create } from \"zustand\";\n\nexport const usePostStore = create((set) =\u003e ({\n  posts: [],\n  setPosts: (posts) =\u003e set({ posts }),\n}));\n```\n\n#### Add New Path Constants\n\n```typescript\n// shared/constants/paths.ts\nexport const APP_PATHS = {\n  // ... existing paths\n  DASHBOARD: \"/dashboard\",\n  SETTINGS: \"/settings\",\n};\n```\n\n---\n\n## 🎨 Theme Toggle Component\n\nThe `ThemeToggle` component provides flexible theme switching with multiple variants.\n\n### Basic Usage\n\n```tsx\nimport { ThemeToggle } from \"@/components/ThemeToggle\";\n\nexport default function Header() {\n  return (\n    \u003cheader\u003e\n      \u003cThemeToggle variant=\"click-small\" /\u003e\n    \u003c/header\u003e\n  );\n}\n```\n\n### Variants\n\n#### Click-Small (Default)\n\n```tsx\n\u003cThemeToggle variant=\"click-small\" /\u003e\n```\n\n- Compact button design\n- Perfect for headers/navigation\n- Single click to toggle theme\n\n#### Slide\n\n```tsx\n\u003cThemeToggle variant=\"slide\" /\u003e\n```\n\n- Animated slide switch design\n- More prominent visual feedback\n- Great for settings pages\n\n### Props\n\n| Prop      | Type                       | Default         | Description        |\n| --------- | -------------------------- | --------------- | ------------------ |\n| `variant` | `\"slide\" \\| \"click-small\"` | `\"click-small\"` | Theme toggle style |\n\n### How It Works\n\n1. Uses `next-themes` for theme management\n2. Syncs across all browser tabs\n3. Persists theme preference to localStorage\n4. Respects system theme preference on first visit\n5. Hydration-safe (prevents hydration mismatch)\n\n### Theme-Aware Components\n\nAll form components automatically respond to theme changes:\n\n- Text inputs, selects, textareas\n- OTP input boxes\n- File uploads\n- Checkboxes and radio groups\n- Labels and error messages\n- Editor with syntax highlighting on links\n\n### Customizing Themes\n\nEdit your Tailwind config to customize light/dark mode colors:\n\n```javascript\n// tailwind.config.js\nexport default {\n  darkMode: \"class\",\n  theme: {\n    extend: {\n      colors: {\n        // Custom colors for light mode\n        // Custom colors for dark mode\n      },\n    },\n  },\n};\n```\n\n### Programmatic Theme Control\n\n```tsx\nimport { useTheme } from \"next-themes\";\n\nexport function ThemeController() {\n  const { theme, setTheme } = useTheme();\n\n  return (\n    \u003cdiv\u003e\n      Current theme: {theme}\n      \u003cbutton onClick={() =\u003e setTheme(\"light\")}\u003eLight\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e setTheme(\"dark\")}\u003eDark\u003c/button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! If you'd like to improve this starter template:\n\n1. **Fork the repository**\n2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)\n3. **Commit your changes** (`git commit -m 'Add some amazing feature'`)\n4. **Push to the branch** (`git push origin feature/amazing-feature`)\n5. **Open a Pull Request**\n\n---\n\n## 📖 Learn More\n\n- [Next.js Documentation](https://nextjs.org/docs)\n- [React Hook Form](https://react-hook-form.com/)\n- [Zustand](https://docs.pmnd.rs/zustand/getting-started/introduction)\n- [TanStack Query](https://tanstack.com/query/latest)\n- [Tailwind CSS](https://tailwindcss.com/docs)\n- [shadcn/ui](https://ui.shadcn.com/)\n\n---\n\n## ⭐ Star This Project\n\nIf you find this starter helpful, please consider giving it a star on GitHub! It helps others discover this template.\n\n**[⭐ Star on GitHub](https://github.com/aceiny/NextJs-Starter-Kit)**\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **Next.js Team** - For the amazing framework\n- **shadcn** - For the beautiful component library\n- **TanStack** - For React Query\n- **Sonner** - For beautiful toasts\n\n---\n\n**Built with ❤️ by developers, for developers**\n\n**Ready to start building?** [View Examples →](http://localhost:3000/example)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faceiny%2Fnextjs-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faceiny%2Fnextjs-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faceiny%2Fnextjs-starter-kit/lists"}