Frontend Next.js Boilerplate (TypeScript + Zod)

A modern, production-ready Next.js 15 boilerplate with TypeScript, Zod validation, Mantine UI, TanStack Query, and Zustand for state management.

🚀 Features

• ⚡️ Next.js 15 with App Router
• 🎯 TypeScript for type safety
• ✅ Zod for schema validation with automatic type inference
• 🎨 Mantine UI for beautiful, accessible components
• 🔄 TanStack Query (React Query) for data fetching and caching
• 🗃️ Zustand for simple and scalable state management
• 📡 Axios for HTTP requests
• 🏗️ Organized project structure with clear separation of concerns

📁 Project Structure

src/
├── app/                    # Next.js app router pages
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Home page
│   ├── mock-form/         # Form example page
│   └── random-facts/      # API integration example
├── components/            # Reusable React components
│   ├── BackButton.tsx
│   └── MockForm.tsx
├── constants/             # Application constants
├── hooks/                 # Custom React hooks
│   ├── useMockMutation.ts
│   └── useRandomFactsQuery.ts
├── layouts/               # Layout components
│   └── BasicAppShellLayout.tsx
├── providers/             # Context providers
│   ├── MantineProvider.tsx
│   ├── QueryClientProvider.tsx
│   └── RootProvider.tsx
├── schema/                # Zod validation schemas
│   └── mockFormSchema.ts
├── services/              # API services
│   ├── api/
│   │   └── apiClient.ts
│   ├── mockFormService.ts
│   └── randomFactsService.ts
├── store/                 # Zustand stores
│   └── store.ts
└── styles/                # Global styles
    └── global.css

🛠️ Tech Stack

• Framework: Next.js 15.1.2
• Language: TypeScript 5+
• Validation: Zod 3.23+ with mantine-form-zod-resolver
• UI Library: Mantine 7.15+
• Data Fetching: TanStack Query 5.62+
• State Management: Zustand 5.0+
• HTTP Client: Axios 1.7+
• Icons: Tabler Icons React

📦 Installation

# Clone the repository
git clone <your-repo-url>

# Navigate to project directory
cd frontend-boilerplate-next

# Install dependencies
npm install

🚀 Getting Started

Run the development server:

npm run dev

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

📝 Available Scripts

npm run dev      # Start development server
npm run build    # Build for production
npm run start    # Start production server
npm run lint     # Run ESLint

🎯 Key Concepts

Zod Schema Validation

Define schemas with automatic TypeScript type inference:

import { z } from "zod";

export const mockFormSchema = z.object({
  name: z.string().min(1, "Name is required"),
  age: z.number().positive("Age must be positive"),
  gender: z.enum(["MALE", "FEMALE"]),
});

// Automatically inferred type
export type MockFormValues = z.infer<typeof mockFormSchema>;

TanStack Query Hooks

export const useRandomFactsQuery = () => {
  return useQuery({
    queryKey: ["randomFacts"],
    queryFn: getRandomFacts,
    enabled: false,
  });
};

Zustand Store

interface CounterStore {
  count: number;
  increment: () => void;
  decrement: () => void;
}

export const useCounterStore = create<CounterStore>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
}));

📚 Examples Included

1. State Management (/) - Zustand counter with localStorage persistence
2. Form Validation (/mock-form) - Mantine Form with Zod validation
3. API Integration (/random-facts) - TanStack Query with external API

🔧 Configuration Files

• tsconfig.json - TypeScript configuration
• next.config.ts - Next.js configuration
• package.json - Dependencies and scripts

🎨 Customization

Adding New Pages

Create a new folder in src/app/:

// src/app/new-page/page.tsx
export default function NewPage() {
  return <div>New Page</div>;
}

Adding New Schemas

Create schemas in src/schema/:

import { z } from "zod";

export const mySchema = z.object({
  // your fields
});

export type MySchemaType = z.infer<typeof mySchema>;

Adding New Hooks

Create hooks in src/hooks/:

import { useQuery } from "@tanstack/react-query";

export const useMyQuery = () => {
  return useQuery({
    queryKey: ["myQuery"],
    queryFn: myService,
  });
};

🚀 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import project on Vercel
3. Deploy automatically

Other Platforms

Build the project:

npm run build
npm run start

📄 License

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

🤝 Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

📖 Learn More

• Next.js Documentation
• TypeScript Documentation
• Zod Documentation
• Mantine Documentation
• TanStack Query Documentation
• Zustand Documentation