Next Modern Starter

A modern, minimal Next.js 15 starter template with Motion animations, Zustand state management, Tailwind CSS v4, and TypeScript. Production-ready with built-in dark mode, engineering best practices, and automatic deployment.

Language: 中文文档 | English

✨ Features

• 🚀 Next.js 15: Latest React framework with App Router and Turbopack
• 🎨 Tailwind CSS v4: Next-generation utility-first CSS framework
• 🐻 Zustand: Lightweight and scalable state management
• 🎭 Motion: Performant animations with declarative API
• 🌗 Dark Mode: Seamless theme switching with system preference support
• 📘 TypeScript: Full type safety with strict mode enabled
• 🛠️ Engineering Tools: ESLint, Prettier, Husky, lint-staged, and Commitlint
• 🚀 GitHub Actions: Automated deployment to GitHub Pages
• 📦 clsx: Conditional className utility for cleaner component code

🎯 Philosophy

This template provides a minimal, production-ready foundation rather than a bloated framework. It includes only the essentials, allowing you to:

• Add your preferred UI component library (shadcn/ui, Ant Design, Material-UI, etc.)
• Integrate any database solution (Prisma, Drizzle, Supabase, etc.)
• Implement authentication (NextAuth, Clerk, Auth0, etc.)
• Scale with your own backend architecture

🚀 Quick Start

Prerequisites

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

Installation

# Clone the repository
git clone https://github.com/crper/next-modern-starter.git
cd next-modern-starter

# Install dependencies
pnpm install

# Start development server with Turbopack
pnpm dev

Open http://localhost:3000 to see your app.

🚀 Deployment

GitHub Pages (Automatic)

Push to the main or master branch to automatically deploy via GitHub Actions:

1. Enable GitHub Pages in your repository settings
2. Set source to "GitHub Actions"
3. Push your code - deployment happens automatically

Vercel

Click the "Deploy with Vercel" button above or:

npx vercel

Other Platforms

This template works with any platform that supports Next.js:

• Netlify
• Railway
• Render
• AWS Amplify

📁 Project Structure

├── .github/
│   └── workflows/
│       └── deploy.yml      # GitHub Pages deployment
├── public/                 # Static assets
│   └── images/            # Optimized images
├── src/
│   ├── app/               # Next.js App Router
│   │   ├── layout.tsx     # Root layout with providers
│   │   ├── page.tsx       # Home page
│   │   └── globals.css    # Global styles and Tailwind
│   ├── components/        # React components
│   │   ├── Counter.tsx    # Counter demo with Zustand
│   │   ├── TodoList.tsx   # Todo demo with animations
│   │   ├── ThemeToggle.tsx # Theme switcher
│   │   └── ThemeProvider.tsx # Theme context provider
│   └── store/             # Zustand stores
│       └── index.ts       # Global state management
├── eslint.config.mjs      # ESLint flat config
├── next.config.ts         # Next.js configuration
├── tailwind.config.ts     # Tailwind CSS v4 config
└── tsconfig.json          # TypeScript configuration

🎨 Styling System

Tailwind CSS v4

• Configuration via CSS @config directive
• Automatic dark mode with dark: variants
• Custom theme variables in globals.css
• Optimized for performance

Dark Mode

Powered by next-themes with:

• System preference detection
• Manual theme switching
• No flash on load
• Persistent selection
• CSS variables for theming

clsx Usage Examples

// Conditional classes
className={clsx(
  'base-class',
  {
    'active-class': isActive,
    'error-class': hasError,
  }
)}

// Multiple conditions
className={clsx(
  'text-sm font-medium',
  isLarge && 'text-lg',
  color === 'primary' && 'text-blue-600'
)}

🔧 Available Scripts

• pnpm dev - Start development server with Turbopack
• pnpm build - Build for production
• pnpm start - Start production server
• pnpm lint - Run ESLint
• pnpm type-check - Check TypeScript types

🌟 State Management

Zustand stores with TypeScript:

// Counter store example
const { count, increment, decrement } = useCounterStore();

// Task store with persistence
const { tasks, addTask, toggleTask } = useTaskStore();

Features:

• Redux DevTools integration
• Persistence middleware
• TypeScript autocompletion
• Minimal boilerplate

🎭 Animation System

Motion (Framer Motion) integration:

// Simple animation
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  Content
</motion.div>

// With AnimatePresence
<AnimatePresence mode="wait">
  {items.map(item => (
    <motion.div key={item.id} exit={{ opacity: 0 }}>
      {item.content}
    </motion.div>
  ))}
</AnimatePresence>

📝 Code Standards

Git Commits

Follow Conventional Commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test updates
• chore: Maintenance tasks

Code Quality

• ESLint with Next.js recommended rules
• Prettier for consistent formatting
• Husky for pre-commit hooks
• TypeScript strict mode

🤝 Contributing

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

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Next.js - The React framework
• Motion - Animation library
• Zustand - State management
• Tailwind CSS - CSS framework
• next-themes - Theme management

---

Happy coding! 🎉