Next.js Template

A comprehensive Next.js template with routing, API routes, loading states, and error boundaries.

Table of Contents

• Features
• Getting Started
• Project Structure
• Component Libraries
  • Hero UI
  • shadcn/ui
  • Chakra UI
• API Endpoints
• SEO Setup
• Learn More
• Deploy

Features

• App Router - File-based routing with layouts and nested routes
• API Routes - RESTful API endpoints (/api/health, /api/data)
• Loading States - Automatic loading UI with loading.tsx files
• Error Boundaries - Graceful error handling with error.tsx files
• TypeScript - Full type safety with TypeScript
• Tailwind CSS - Utility-first CSS framework
• Component Libraries - Optional setup for Hero UI, shadcn/ui, or Chakra UI
• Custom 404 Page - Branded not-found page
• Setup Script - Interactive CLI to customize your project

Getting Started

1. Run the Setup Script

The interactive setup script will configure everything for you:

npm run setup "My Project Name"

Or run it interactively (it will prompt for the project name):

npm run setup

What the setup script does:

• ✅ Updates all template references with your project name
• ✅ Cleans and installs all dependencies (npm ci)
• ✅ Presents an interactive menu to choose a component library
• ✅ Automatically installs and configures your selected library:
  • Hero UI: Installs packages, adds provider to layout.tsx, updates tailwind.config.ts
  • shadcn/ui: Initializes shadcn, installs 6 common components (button, card, input, label, dialog, dropdown-menu)
  • Chakra UI: Installs packages and adds ChakraProvider to layout.tsx
  • None: Skip component library installation
• ✅ Components are ready to use immediately after setup!

2. Start Development

After setup completes, start the development server:

npm run dev

Open http://localhost:3000 with your browser to see the result.

Project Structure

src/app/
├── layout.tsx          # Root layout
├── page.tsx            # Home page
├── loading.tsx         # Root loading UI
├── error.tsx           # Root error boundary
├── not-found.tsx       # 404 page
├── about/
│   ├── page.tsx        # About page
│   ├── loading.tsx     # About loading UI
│   └── error.tsx       # About error boundary
├── dashboard/
│   ├── layout.tsx      # Dashboard layout with sidebar
│   ├── page.tsx        # Dashboard page
│   ├── loading.tsx     # Dashboard loading UI
│   └── settings/
│       └── page.tsx    # Nested route
└── api/
    ├── health/
    │   └── route.ts    # Health check endpoint
    └── data/
        └── route.ts    # CRUD data endpoint

Component Libraries

The setup script provides fully automated installation and configuration for popular component libraries:

Hero UI

React components built on top of Tailwind CSS with beautiful design and accessibility.

Automatic Setup:

• ✅ Installs @heroui/react and framer-motion
• ✅ Adds HeroUIProvider to layout.tsx
• ✅ Updates tailwind.config.ts with Hero UI plugin

Usage after setup:

import { Button, Card, Input } from '@heroui/react';

<Button color="primary">Click me</Button>

Documentation: https://www.heroui.com

shadcn/ui

Beautifully designed components built with Radix UI and Tailwind CSS.

Automatic Setup:

• ✅ Initializes shadcn/ui with default configuration
• ✅ Auto-installs 6 common components:
  • button, card, input, label, dialog, dropdown-menu
• ✅ Creates components/ui directory structure

Usage after setup:

import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";

<Button variant="default">Click me</Button>

Add more components:

npx shadcn@latest add [component-name]

Documentation: https://ui.shadcn.com

Chakra UI

Simple, modular and accessible component library for React applications.

Automatic Setup:

• ✅ Installs @chakra-ui/react, @emotion/react, @emotion/styled, and framer-motion
• ✅ Adds ChakraProvider to layout.tsx
• ✅ Configures "use client" directive

Usage after setup:

import { Button, Box, Card, Input } from '@chakra-ui/react';

<Button colorScheme="blue">Click me</Button>

Documentation: https://chakra-ui.com

None

Skip component library installation and use your own preferred solution or add one manually later.

API Endpoints

Health Check

GET /api/health

Data CRUD Operations

GET    /api/data        # Get all items
GET    /api/data?id=1   # Get item by ID
POST   /api/data        # Create new item
PUT    /api/data        # Update item
DELETE /api/data?id=1   # Delete item

Learn More

To learn more about Next.js, check out:

• Next.js Documentation
• Next.js App Router
• Learn Next.js

SEO Setup

This template includes a comprehensive SEO setup script that can be run standalone:

npm run seo-setup

Using a Template File

For faster setup or CI/CD automation, you can use a template file:

1. Copy the template:

   cp seo-template.json my-seo-config.json

2. Edit the configuration in my-seo-config.json:

   {
     "siteName": "My Awesome Site",
     "siteTagline": "Building amazing things",
     "siteUrl": "https://example.com",
     "author": "Your Name",
     "locale": "en",
     "businessType": "saas",
     "keywords": ["nextjs", "react", "typescript"],
     "social": {
       "twitter": "yourusername",
       "facebook": "https://facebook.com/yourpage",
       "linkedin": "https://linkedin.com/in/yourprofile"
     }
   }

3. Run setup with the template:

   npm run seo-setup -- --template=my-seo-config.json

Interactive Mode

The script also supports interactive mode where it will prompt you for all information:

npm run seo-setup

You can also choose to use a template file during the interactive session.

What Gets Generated

The SEO setup creates:

• src/lib/seo.config.ts - Centralized SEO configuration
• src/lib/metadata-helper.ts - Helper functions for page metadata
• src/lib/structured-data.tsx - JSON-LD schema helpers
• src/app/sitemap.ts - Automatic sitemap generation
• src/app/robots.ts - SEO-friendly robots.txt
• src/app/manifest.ts - PWA manifest
• docs/SEO_GUIDE.md - Complete SEO guide

Deploy

Deploy your Next.js app using Vercel or any Node.js hosting platform.

Check out the Next.js deployment documentation for more details.