{"_id":"@ashutoshdash/nextjs-mantine-boilerplate","name":"@ashutoshdash/nextjs-mantine-boilerplate","dist-tags":{"latest":"1.2.0"},"versions":{"1.2.0":{"name":"@ashutoshdash/nextjs-mantine-boilerplate","version":"1.2.0","description":"A modern, production-ready boilerplate for building web applications with Next.js 16, React 19, and Mantine UI v8","bin":{"create-nextjs-mantine-app":"bin/cli.js","nextjs-mantine-boilerplate":"bin/cli.js"},"keywords":["nextjs","mantine","boilerplate","template","react","typescript","dashboard"],"author":{"name":"Ashutosh Dash"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate.git"},"private":false,"scripts":{"dev":"next dev","build":"next build","start":"next start","lint":"biome check","format":"biome format --write","analyze":"cross-env ANALYZE=true next build","prepare":"husky"},"lint-staged":{"*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}":["biome check --write --no-errors-on-unmatched --colors=off"]},"dependencies":{"@mantine/core":"^8.3.10","@mantine/form":"^8.3.10","@mantine/hooks":"^8.3.10","@mantine/modals":"^8.3.10","@mantine/notifications":"^8.3.10","@tabler/icons-react":"^3.36.0","@tanstack/react-query":"^5.90.12","@vercel/functions":"^3.3.4","@vercel/speed-insights":"^1.3.1","axios":"^1.13.2","dayjs":"^1.11.19","i18next-browser-languagedetector":"^8.2.0","js-cookie":"^3.0.5","next":"16.0.10","react":"19.2.1","react-dom":"19.2.1","react-i18next":"^16.5.0","react-query-ease":"^0.0.6","zustand":"^5.0.9"},"devDependencies":{"@biomejs/biome":"2.2.0","@commitlint/cli":"^20.2.0","@commitlint/config-conventional":"^20.2.0","@next/bundle-analyzer":"^16.0.10","@types/js-cookie":"^3.0.6","@types/node":"^20","@types/react":"^19","@types/react-dom":"^19","babel-plugin-react-compiler":"1.0.0","cross-env":"^10.1.0","husky":"^9.1.7","lint-staged":"^16.2.7","typescript":"^5"},"_id":"@ashutoshdash/nextjs-mantine-boilerplate@1.2.0","gitHead":"e0583475ef7dd98088ee458e038c4c57cc25c111","bugs":{"url":"https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate/issues"},"homepage":"https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate#readme","_nodeVersion":"22.18.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-tpEbJfWSN++YCN4dhG4De1YcwiYf4pEDGmLQclDy0yHpMkb2jcBaGKlT3kbPgTNHf7OvkkoENYBtkwdAbTcBIQ==","shasum":"5e7d7815537f687019de387b70eadfd73af42155","tarball":"https://registry.npmjs.org/@ashutoshdash/nextjs-mantine-boilerplate/-/nextjs-mantine-boilerplate-1.2.0.tgz","fileCount":115,"unpackedSize":466394,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG1TkplsG2K8Mu2QZOCBfOhPFSRMULDx07Y7AhP9g/rZAiEAtEMPw/7iNzA7/GUG/pAViPn+5x4rH3VWTugzlGBJu8Y="}]},"_npmUser":{"name":"ashutoshdash","email":"dashashutosh1999@gmail.com"},"directories":{},"maintainers":[{"name":"ashutoshdash","email":"dashashutosh1999@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nextjs-mantine-boilerplate_1.2.0_1766659313058_0.1396328923304364"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-25T10:41:52.964Z","1.2.0":"2025-12-25T10:41:53.234Z","modified":"2025-12-25T10:41:53.529Z"},"maintainers":[{"name":"ashutoshdash","email":"dashashutosh1999@gmail.com"}],"description":"A modern, production-ready boilerplate for building web applications with Next.js 16, React 19, and Mantine UI v8","homepage":"https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate#readme","keywords":["nextjs","mantine","boilerplate","template","react","typescript","dashboard"],"repository":{"type":"git","url":"git+https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate.git"},"author":{"name":"Ashutosh Dash"},"bugs":{"url":"https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate/issues"},"license":"MIT","readme":"# Nextjs Mantine Boilerplate\n\n\n\n\n\n\n\n\n\n\n[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fnext.js%2Ftree%2Fcanary%2Fexamples%2Fhello-world&env=NEXT_PUBLIC_COINGECKO_API_URL,NEXT_PUBLIC_COINGECKO_API_KEY&envDescription=API%20keys%20need%20for%20the%20dashboard%2C%20not%20compulsory%20if%20you%20want%20to%20remove%20the%20predefined%20page.&envLink=https%3A%2F%2Fdocs.coingecko.com%2F)\n\n
\n\nA modern, production-ready boilerplate for building web applications with Next.js 16, React 19, and Mantine UI v8. This template includes everything you need to kickstart your project with best practices, TypeScript, state management, and a beautiful UI component library.\n\n**Key Highlight:** Powered by **react-query-ease** - a simplified API client that makes data fetching as easy as calling a function, eliminating boilerplate while maintaining full TypeScript support and TanStack Query's powerful caching.\n\n**Perfect for:** Building dashboards, admin panels, SaaS applications, and modern web apps.\n\n## š” Why Use This Boilerplate?\n\n### šÆ Dashboard-First Architecture\n\nUnlike generic Next.js templates, this boilerplate is **specifically designed for dashboard applications**. It includes:\n\n- **Complete AppShell Layout**: Pre-configured dashboard layout with responsive header, sidebar, and mobile drawer navigation\n- **Protected Route Structure**: Organized route groups `(auth)` and `(protected)` with proper layout nesting\n- **Ready-to-Use Components**: `DashboardHeader` and `DashboardSidebar` components with theme toggle, user menu, and navigation\n- **Real-World Examples**: Four complete dashboard pages (Markets, Trending, Favorites, Portfolio) demonstrating production patterns\n- **State Management for Dashboards**: Zustand stores with persistence for user preferences (currency, theme, etc.)\n\n### š Simplified API Integration with react-query-ease\n\nOne of the standout features is **react-query-ease**, which dramatically simplifies API calls compared to traditional TanStack Query setups:\n\n**Traditional Approach (Verbose):**\n\n```typescript\nconst { data, isLoading, error } = useQuery({\n queryKey: [\"markets\", params],\n queryFn: async () => {\n const response = await axios.get(\"/api/markets\", { params });\n return response.data;\n },\n});\n```\n\n**With react-query-ease (Simple):**\n\n```typescript\nconst { coins, isLoading } = useMarkets({\n vs_currency: \"usd\",\n per_page: 20,\n});\n```\n\n**Key Benefits:**\n\n- ā
**Zero Boilerplate**: Create API clients with a single configuration\n- ā
**Type-Safe Hooks**: Automatic TypeScript inference with minimal setup\n- ā
**Built-in Caching**: Leverages TanStack Query's powerful caching without manual configuration\n- ā
**Easy to Extend**: Add new endpoints by simply creating new hooks\n- ā
**Perfect for Dashboards**: Ideal for applications that need multiple data sources, pagination, filtering, and real-time updates\n\n### š ļø Modern & Production-Ready\n\n- **Latest Tech Stack**: Next.js 16, React 19 with React Compiler, Mantine v8, TypeScript 5\n- **Developer Experience**: Biome (faster than ESLint/Prettier), Husky, lint-staged, commitlint\n- **Best Practices**: Error boundaries, skeleton loaders, theme system, responsive design\n- **Type Safety**: Full TypeScript coverage with proper type definitions\n\n### š Ideal Use Cases\n\n- **Admin Dashboards**: Analytics, user management, content management\n- **SaaS Applications**: Multi-tenant dashboards with data visualization\n- **E-commerce Admin Panels**: Product management, order tracking, analytics\n- **Financial Dashboards**: Portfolio tracking, market data, reporting\n- **Internal Tools**: Company dashboards, reporting tools, data management interfaces\n\n**Bottom Line**: This template saves weeks of setup time by providing a complete, production-ready foundation specifically optimized for dashboard applications, with simplified API integration that makes data fetching as easy as calling a function.\n\n## š Features\n\n- **ā” Next.js 16 App Router**: Latest Next.js features with App Router architecture\n- **āļø React 19**: Cutting-edge React with React Compiler enabled\n- **šØ Mantine UI v8**: Beautiful, accessible components out of the box\n- **š TypeScript**: Full type safety throughout the codebase\n- **šļø State Management**:\n - Zustand for client-side global state\n - TanStack Query for server state and API calls\n- **š Simplified API Client**: react-query-ease for zero-boilerplate API integration with automatic TypeScript inference\n- **š Theme Support**: Dark/light mode with system preference detection\n- **š± Responsive Design**: Mobile-first, fully responsive layouts\n- **āļø Developer Experience**:\n - Biome for fast linting and formatting\n - Husky + lint-staged for Git hooks\n - Conventional commits with commitlint\n - TypeScript strict mode\n- **šÆ Best Practices**: Error boundaries, skeleton loaders, and optimized performance\n\n## š ļø Tech Stack\n\n- **Framework**: [Next.js 16](https://nextjs.org/) (App Router)\n- **UI Library**: [Mantine v8](https://mantine.dev/)\n- **Language**: TypeScript\n- **State Management**:\n - [Zustand](https://zustand-demo.pmnd.rs/) for global state\n - [TanStack Query](https://tanstack.com/query) for server state\n- **API Client**: [react-query-ease](https://www.npmjs.com/package/react-query-ease)\n- **Icons**: [Tabler Icons](https://tabler.io/icons)\n- **Linting/Formatting**: [Biome](https://biomejs.dev/)\n- **Git Hooks**: Husky + lint-staged\n\n## š Prerequisites\n\n- Node.js 18+\n- npm, yarn, pnpm, or bun\n\n## š Getting Started\n\n### Quick Start (Recommended)\n\nCreate a new project using npx:\n\n```bash\nnpx @ashutoshdash/nextjs-mantine-boilerplate\n```\n\nThe CLI will prompt you for a project name and set up everything automatically!\n\n### Manual Installation\n\nAlternatively, you can clone the repository:\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate.git\ncd nextjs-mantine-boilerplate\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 (if needed):\n\n```bash\ncp env.example .env.local\n```\n\nEdit `.env.local` and add any required environment variables for your project.\n\n4. Run the development server:\n\n```bash\nnpm run dev\n# or\nyarn dev\n# or\npnpm dev\n```\n\n5. Open [http://localhost:3000](http://localhost:3000) in your browser.\n\n## š Project Structure\n\n```\nsrc/\nāāā api/ # API configuration and hooks\nā āāā config.ts # API client setup\nā āāā hooks/ # Custom React Query hooks\nā āāā useCoinGecko.ts\nāāā app/ # Next.js app directory\nā āāā (auth)/ # Authentication routes\nā ā āāā login/\nā āāā (protected)/ # Protected routes\nā ā āāā _components/ # Shared protected components\nā ā ā āāā DashboardHeader.tsx\nā ā ā āāā DashboardSidebar.tsx\nā ā āāā home/ # Dashboard pages\nā ā ā āāā markets/ # Markets page\nā ā ā āāā trending/ # Trending coins page\nā ā ā āāā favorites/ # Favorites page\nā ā ā āāā portfolio/ # Portfolio page\nā ā āāā layout.tsx # Protected layout with AppShell\nā āāā api/ # API routes\nā āāā _components/ # Shared components\nā āāā error.tsx # Error boundary\nā āāā loading.tsx # Loading component\nā āāā layout.tsx # Root layout\nāāā components/ # Reusable components\nāāā providers/ # Context providers\nā āāā app-provider.tsx # Mantine and Query providers\nā āāā query-provider.tsx # TanStack Query setup\nāāā store/ # Zustand stores\nā āāā useLocalStore.ts # Local storage state\nā āāā types.ts # Store type definitions\nāāā utils/ # Utility functions\n āāā format.ts # Currency and number formatting\n āāā dayjs.utils.ts # Date utilities\n```\n\n## š Available Scripts\n\n- `npm run dev` - Start development server\n- `npm run build` - Build for production\n- `npm run start` - Start production server\n- `npm run lint` - Run Biome linter\n- `npm run format` - Format code with Biome\n- `npm run analyze` - Analyze bundle size\n\n## šØ What's Included\n\n### Project Structure\n\n- **App Router Setup**: Next.js 16 App Router with route groups\n- **Protected Routes**: Example protected route layout with AppShell\n- **API Routes**: Next.js API route handlers\n- **Component Organization**: Well-structured component hierarchy\n- **State Management**: Zustand stores and TanStack Query hooks\n- **Utilities**: Formatting, date manipulation, and API helpers\n\n### Example Features\n\n- **Dashboard Layout**: AppShell with header and sidebar\n- **Theme Toggle**: Switch between light/dark/system themes\n- **Error Handling**: Global error boundary and not-found pages\n- **Loading States**: Skeleton loaders for better UX\n- **Type Safety**: Full TypeScript coverage\n- **Utility Functions**: Pre-built formatters for currency, percentages, numbers, dates, and time with localization support\n\n## š§ Configuration\n\n### Environment Variables\n\nCreate a `.env.local` file based on `env.example` and add your environment variables. All public variables must be prefixed with `NEXT_PUBLIC_`.\n\n### Theme Configuration\n\nThe app uses Mantine's theme system. You can customize the theme in `src/providers/app-provider.tsx`:\n\n```typescript\nconst theme = createTheme({\n fontFamily: \"var(--font-nunito), sans-serif\",\n // Add your customizations here\n});\n```\n\n### API Integration with react-query-ease\n\nThe boilerplate uses **react-query-ease** to simplify API integration. This powerful wrapper around TanStack Query eliminates boilerplate while maintaining all the benefits of React Query.\n\n#### Setting Up Your API Client\n\nCreate an API client in `src/api/config.ts`:\n\n```typescript\nimport { createApiClient } from \"react-query-ease\";\n\nexport const myApi = createApiClient({\n baseURL: process.env.NEXT_PUBLIC_API_URL || \"https://api.example.com\",\n headers: {\n Authorization: `Bearer ${token}`,\n },\n});\n```\n\n#### Creating Custom Hooks\n\nCreate hooks in `src/api/hooks/` following this pattern:\n\n```typescript\nimport { myApi } from \"../config\";\n\nexport const useMyData = (params?: MyParams) => {\n const query = myApi.useQuery({\n url: \"/endpoint\",\n method: \"GET\",\n key: [\"myData\", params],\n params: {\n // Your query parameters\n },\n });\n\n return {\n data: query.data ?? [],\n isLoading: query.isLoading,\n ...query, // Includes error, refetch, etc.\n };\n};\n```\n\n#### Why react-query-ease?\n\n- **90% Less Code**: No need to write query functions, manual error handling, or cache key management\n- **Type-Safe**: Full TypeScript inference from your API responses\n- **Automatic Caching**: Leverages TanStack Query's caching without configuration\n- **Easy to Extend**: Add new endpoints by creating simple hook functions\n- **Perfect for Dashboards**: Ideal for applications with multiple data sources, pagination, and real-time updates\n\nSee `src/api/hooks/useCoinGecko.ts` for complete examples of how to use react-query-ease in your project.\n\n## šÆ Best Practices\n\n- TypeScript for type safety\n- React Query for efficient data fetching and caching\n- Zustand for lightweight state management\n- Biome for fast linting and formatting\n- Error boundaries for graceful error handling\n- Skeleton loaders for better UX during data fetching\n\n## š License\n\nThis project is private and proprietary.\n\n## š¤ Contributing\n\nWe welcome contributions to the Next.js Mantine Boilerplate! This document provides guidelines and instructions for contributing to the project.\n\n### Getting Started\n\n1. **Fork the repository** and clone your fork:\n\n ```bash\n git clone https://github.com/AshutoshDash1999/nextjs-mantine-boilerplate.git\n cd nextjs-mantine-boilerplate\n ```\n\n Or if you've already forked it, clone your fork:\n\n ```bash\n git clone https://github.com//nextjs-mantine-boilerplate.git\n cd nextjs-mantine-boilerplate\n ```\n\n2. **Create a branch** for your changes:\n\n ```bash\n git checkout -b feature/your-feature-name\n # or\n git checkout -b fix/your-bug-fix\n ```\n\n3. **Install dependencies**:\n\n ```bash\n npm install\n ```\n\n4. **Make your changes** following our coding standards (see below)\n\n5. **Test your changes**:\n\n ```bash\n npm run lint\n npm run build\n ```\n\n6. **Commit your changes** using conventional commits:\n\n ```bash\n git commit -m \"feat: add new feature\"\n # or\n git commit -m \"fix: resolve bug in component\"\n ```\n\n7. **Push to your fork** and open a Pull Request\n\n### Coding Standards\n\n#### TypeScript\n\n- Always use TypeScript with proper typing\n- Avoid using `any` type - use `unknown` or proper types instead\n- Use type inference when appropriate, but be explicit for function parameters and return types\n\n#### React Patterns\n\n- Use `\"use client\"` directive for all interactive components\n- Keep components focused and single-purpose\n- Use custom hooks for reusable logic\n- Prefer named exports for components\n\n#### Mantine v8\n\n- **Always use Mantine v8 patterns** - check [Mantine v8 docs](https://mantine.dev/)\n- Use component props for styling when possible\n- Follow Mantine's spacing and color systems\n- Use responsive props for mobile-first design\n\n#### File Organization\n\n- Co-locate related components in the same directory\n- Use `_components/` folders for page-specific components\n- Keep shared components in `src/app/_components/` or `src/components/`\n- Export components through `index.ts` files\n\n#### State Management\n\n- Use **Zustand** for client-side global state\n- Use **TanStack Query** for server state and API calls\n- Keep state as local as possible\n\n#### Code Quality\n\n- Run `npm run lint` before committing\n- Run `npm run format` to auto-format code\n- Ensure all TypeScript errors are resolved\n- Write self-documenting code with clear variable names\n\n### Commit Message Guidelines\n\nWe follow [Conventional Commits](https://www.conventionalcommits.org/):\n\n- `feat:` - New feature\n- `fix:` - Bug fix\n- `docs:` - Documentation changes\n- `style:` - Code style changes (formatting, etc.)\n- `refactor:` - Code refactoring\n- `perf:` - Performance improvements\n- `test:` - Adding or updating tests\n- `chore:` - Maintenance tasks\n\nExamples:\n\n```\nfeat: add currency selector to dashboard header\nfix: resolve navigation issue in not-found page\ndocs: update contribution guidelines\nrefactor: extract API hooks into separate file\n```\n\n### Pull Request Process\n\n1. **Update documentation** if you've changed functionality\n2. **Add tests** if applicable (we're working on adding a test suite)\n3. **Ensure the build passes**: `npm run build`\n4. **Ensure linting passes**: `npm run lint`\n5. **Update the CHANGELOG** if applicable\n6. **Link related issues** in your PR description\n7. **Request review** from maintainers\n\n### PR Template\n\nWhen opening a PR, please fill out the template with:\n\n- Description of changes\n- Type of change (feature, bug fix, etc.)\n- Testing instructions\n- Screenshots (if UI changes)\n- Checklist of completed items\n\n### Development Workflow\n\n1. **Before starting work**, check existing issues and PRs to avoid duplicate work\n2. **Create an issue** first for significant changes to discuss the approach\n3. **Keep PRs focused** - one feature or fix per PR\n4. **Keep PRs small** - break large changes into smaller, reviewable PRs\n5. **Respond to feedback** promptly and be open to suggestions\n\n### Reporting Bugs\n\nWhen reporting bugs, please use the bug report template and include:\n\n- Clear description of the issue\n- Steps to reproduce\n- Expected vs actual behavior\n- Environment details (OS, browser, Node version)\n- Screenshots if applicable\n\n### Suggesting Features\n\nWhen suggesting features, please use the feature request template and include:\n\n- Clear description of the feature\n- Use case and motivation\n- Proposed implementation (if you have ideas)\n- Alternatives considered\n\n### Code Review\n\n- All PRs require at least one approval before merging\n- Be respectful and constructive in reviews\n- Address feedback promptly\n- Ask questions if something is unclear\n\n### Questions?\n\nIf you have questions about contributing:\n\n- Open a discussion in GitHub Discussions\n- Ask in an issue with the `question` label\n- Check existing documentation in `AGENTS.md`\n\nThank you for contributing! š\n\n## š§ Support\n\nFor support, please open an issue in the repository using the appropriate template.\n\n---\n\nBuilt with ā¤ļø using Next.js, React, and Mantine\n","readmeFilename":"README.md","_rev":"1-85a30f7d07bf8dc2b8588df6132c4b68"}