244 lines
4.6 KiB
Markdown
244 lines
4.6 KiB
Markdown
# Usage Guide
|
|
|
|
## Creating a New Project from This Template
|
|
|
|
### Method 1: Copy and Setup (Recommended)
|
|
|
|
This is the simplest and fastest method:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# Clone from GitHub (no git history)
|
|
npx degit yourusername/nextjs-starter my-new-project
|
|
cd my-new-project
|
|
./setup.sh
|
|
```
|
|
|
|
### Method 3: Manual Setup
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```typescript
|
|
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`:
|
|
|
|
```bash
|
|
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)
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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
|
|
|
|
```bash
|
|
# Use a different port
|
|
npm run dev -- -p 3001
|
|
```
|
|
|
|
### Clear Next.js Cache
|
|
|
|
```bash
|
|
rm -rf .next
|
|
npm run dev
|
|
```
|
|
|
|
### TypeScript Errors
|
|
|
|
```bash
|
|
# Restart TypeScript server in your editor
|
|
# Or run type check:
|
|
npx tsc --noEmit
|
|
```
|
|
|
|
## Updating Dependencies
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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](https://nextjs.org/docs)
|
|
- [Tailwind CSS Docs](https://tailwindcss.com/docs)
|
|
- [shadcn/ui Docs](https://ui.shadcn.com)
|
|
- [React Docs](https://react.dev)
|