nextjs-web-app/USAGE.md

Usage Guide

Creating a New Project from This Template

Method 1: Copy and Setup (Recommended)

This is the simplest and fastest method:

# Copy the template
cp -r ~/Projects/nextjs-starter ~/Projects/my-new-project
cd ~/Projects/my-new-project

# Run setup script
./setup.sh

Method 2: Using degit with GitHub

After pushing this template to GitHub:

# Clone from GitHub (no git history)
npx degit yourusername/nextjs-starter my-new-project
cd my-new-project
./setup.sh

Method 3: Manual Setup

# Copy the template
cp -r ~/Projects/nextjs-starter ~/Projects/my-new-project
cd ~/Projects/my-new-project

# Remove git history
rm -rf .git

# Update package.json name manually
# Edit package.json and change "name": "nextjs-starter" to your project name

# Install dependencies
npm install

# Initialize git (optional)
git init
git add .
git commit -m "Initial commit"

# Start development
npm run dev

What the Setup Script Does

The setup.sh script:

1. ✅ Prompts for your project name
2. ✅ Updates package.json with your project name
3. ✅ Installs all dependencies
4. ✅ Initializes a new git repository
5. ✅ Creates initial commit

Adding shadcn/ui Components

The template is pre-configured for shadcn/ui. Add components:

# Add individual components
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add dialog
npx shadcn@latest add input
npx shadcn@latest add label

# Add multiple at once
npx shadcn@latest add button card dialog input label

Components will be added to src/components/ui/.

Common Customizations

1. Change App Title and Description

Edit src/app/layout.tsx:

export const metadata: Metadata = {
  title: "Your App Name",
  description: "Your app description",
};

2. Customize Theme Colors

Edit src/app/globals.css - look for the :root and .dark sections.

3. Add Environment Variables

Create .env.local:

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://...

4. Add Custom Fonts

Edit src/app/layout.tsx to add Google Fonts or local fonts.

5. Configure Deployment

Vercel (Recommended)

npm install -g vercel
vercel

Other Platforms

• Build: npm run build
• Start: npm start
• Output: .next directory

Project Structure Explained

src/
├── app/                    # Next.js App Router
│   ├── globals.css        # Global styles + Tailwind
│   ├── layout.tsx         # Root layout (wraps all pages)
│   └── page.tsx           # Home page (/)
├── components/
│   └── ui/                # shadcn/ui components
├── lib/
│   └── utils.ts           # Utility functions (cn helper)
└── hooks/                 # Custom React hooks (create as needed)

Tips & Best Practices

1. Use the cn Utility

For conditional classes:

import { cn } from "@/lib/utils";

<div className={cn(
  "base-classes",
  condition && "conditional-classes",
  variant === "primary" && "primary-classes"
)} />

2. Organize Components

src/components/
├── ui/              # shadcn/ui components
├── layout/          # Layout components (Header, Footer, etc.)
├── features/        # Feature-specific components
└── shared/          # Shared/common components

3. Use TypeScript

Always define types for props:

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: "primary" | "secondary";
}

export function Button({ label, onClick, variant = "primary" }: ButtonProps) {
  // ...
}

4. Environment Variables

• NEXT_PUBLIC_* - Exposed to browser
• Others - Server-side only

Troubleshooting

Port Already in Use

# Use a different port
npm run dev -- -p 3001

Clear Next.js Cache

rm -rf .next
npm run dev

TypeScript Errors

# Restart TypeScript server in your editor
# Or run type check:
npx tsc --noEmit

Updating Dependencies

# Check for updates
npm outdated

# Update all to latest
npm update

# Update specific package
npm install next@latest

Updating the Template

To pull updates from the template into an existing project:

cd ~/Projects/my-existing-project

# Add template as remote
git remote add template ~/Projects/nextjs-starter

# Fetch and merge updates
git fetch template
git merge template/main --allow-unrelated-histories

Getting Help

• Next.js Docs
• Tailwind CSS Docs
• shadcn/ui Docs
• React Docs