Next.js Template

A production-ready Next.js boilerplate with advanced theming, beautiful UI components, and modern best practices.

Features

• Advanced Theming System - Multiple color themes with light/dark mode support
• Type-Safe - Full TypeScript support throughout
• Modern Colors - OKLCH color space for better perceptual uniformity
• UI Components - Pre-built components with Radix UI primitives
• Accessible - WCAG compliant components
• Responsive - Mobile-first design approach
• Fast - Optimized with Next.js 15 and Tailwind CSS v4
• Developer Experience - ESLint, Biome, TypeScript configured

Getting Started

Prerequisites

• Node.js 24+ (recommend using nvm to manage versions)
• pnpm 10+ (enabled through corepack)

Installation

# Install dependencies
pnpm install

# Run the development server
pnpm dev

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

Theming System

This template includes a theming system with:

• 5 Color Themes: Neutral, Blue, Green, Purple, Orange
• Light/Dark Mode: Automatic system detection with manual override
• Runtime Switching: Change themes without page reload
• Type-Safe: Full TypeScript support for themes

Quick Theme Usage

import { useTheme } from "@/src/providers/theme-provider";
import { ThemeSwitcher } from "@/src/components/theme-switcher";

export function MyComponent() {
  const { theme, setTheme, actualTheme } = useTheme();

  return (
    <div>
      <ThemeSwitcher />
      <button onClick={() => setTheme("dark")}>Dark Mode</button>
    </div>
  );
}

For detailed theming documentation, see THEMING.md.

Tech Stack

• Framework: Next.js 15
• Styling: Tailwind CSS v4
• UI Components: Radix UI + shadcn/ui (New York style)
• Type Safety: TypeScript
• Code Quality: Biome, ESLint
• Fonts: Geist Sans & Mono

UI Components

Pre-built, themeable components included:

• Button - Multiple variants and sizes
• Card - Flexible card layouts
• Badge - Status and category indicators
• Input - Form inputs with validation states
• Theme Switcher - Light/dark/system mode toggle

All components are fully typed and support custom className overrides.

Component Usage

import { Button, Card, Badge } from "@/src/components/ui";

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description</CardDescription>
  </CardHeader>
  <CardContent>
    <Badge variant="secondary">New</Badge>
  </CardContent>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>

Project Structure

src/
├── app/                    # Next.js app directory
│   ├── demo/              # Theme demo page
│   ├── globals.css        # Global styles & CSS variables
│   ├── layout.tsx         # Root layout with theme provider
│   └── page.tsx           # Home page
├── components/
│   ├── ui/                # Reusable UI components
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Badge.tsx
│   │   └── Input.tsx
│   └── theme-switcher.tsx # Theme toggle component
├── config/
│   └── themes.ts          # Theme configurations
├── lib/
│   └── utils.ts           # Utility functions (cn helper, etc.)
└── providers/
    └── theme-provider.tsx # Theme context provider

🛠️ Available Scripts

# Development
pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm start        # Start production server

# Code Quality
pnpm check        # Check code with Biome
pnpm check:fix    # Fix code issues with Biome
pnpm lint         # Lint code
pnpm lint:fix     # Fix linting issues
pnpm format       # Check formatting
pnpm format:fix   # Fix formatting

Demo Pages

• Home (/) - Landing page showcasing the template
• Demo (/demo) - Interactive theme demonstration with all components and color schemes

Creating Custom Themes

Add your own theme in src/config/themes.ts:

export const themes = {
  myTheme: {
    light: {
      background: "oklch(0.99 0.005 200)",
      foreground: "oklch(0.15 0.02 200)",
      primary: "oklch(0.55 0.20 200)",
      // ... other colors
    },
    dark: {
      background: "oklch(0.12 0.02 200)",
      foreground: "oklch(0.95 0.01 200)",
      primary: "oklch(0.65 0.20 200)",
      // ... other colors
    },
  },
} as const;

See THEMING.md for comprehensive theming documentation.

Best Practices

1. Use Theme Variables - Always use CSS variables for colors (e.g., bg-primary instead of bg-blue-500)
2. Test Both Modes - Check components in light and dark modes
3. Type Safety - Leverage TypeScript for better developer experience
4. Accessibility - Maintain sufficient color contrast (WCAG AA: 4.5:1)
5. Component Composition - Build complex UIs from simple, reusable components

🚢 Deployment

Vercel (Recommended)

The easiest way to deploy:

Other Platforms

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

• Netlify
• Railway
• Fly.io
• AWS Amplify
• Docker

See Next.js deployment docs for details.

VS Code Setup (Recommended)

Install these extensions for the best development experience:

• Biome - Formatting and linting
• TypeScript - Enhanced TypeScript support
• Tailwind CSS IntelliSense - Autocomplete for Tailwind classes

Learn More

• Next.js Documentation
• Tailwind CSS v4
• Radix UI Primitives
• shadcn/ui
• OKLCH Color Space
• Biome Documentation

License

MIT - Feel free to use this template for any project!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Note: This template uses Biome for code quality. If you prefer ESLint, the default config is still included and can be used instead.