Initial template: Next.js Web App starter template

2026-03-12 23:40:50 +00:00 · 2026-03-12 23:40:50 +00:00 · 46d1f10fc1
commit 46d1f10fc1
18 changed files with 1226 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.idea
--- a/ALTERNATIVES.md
+++ b/ALTERNATIVES.md
@ -0,0 +1,232 @@
+# Alternative Approaches to Template Management
+
+## Current Approach: Simple Copy
+
+```bash
+cp -r ~/Projects/nextjs-starter ~/Projects/my-project
+cd ~/Projects/my-project
+./setup.sh
+```
+
+**Pros:**
+- ✅ Simple and fast
+- ✅ No external dependencies
+- ✅ Works offline
+- ✅ Easy to understand
+
+**Cons:**
+- ❌ Feels "low-tech"
+- ❌ Manual process
+- ❌ No built-in versioning
+
+## Better Alternatives
+
+### 1. GitHub Template + create-next-app (Recommended)
+
+**Setup once:**
+```bash
+cd ~/Projects/nextjs-starter
+gh repo create nextjs-starter --public --source=. --remote=origin
+git push -u origin main
+# Enable "Template repository" in GitHub Settings
+```
+
+**Usage:**
+```bash
+npx create-next-app my-project --example https://github.com/yourusername/nextjs-starter
+cd my-project
+npm run dev
+```
+
+**Pros:**
+- ✅ Official Next.js tool
+- ✅ Industry standard
+- ✅ Automatic npm install
+- ✅ Clean (no git history)
+- ✅ Shareable with team
+
+**Cons:**
+- ❌ Requires GitHub
+- ❌ Requires internet
+
+---
+
+### 2. degit (Fast, No Git History)
+
+**Usage:**
+```bash
+npx degit yourusername/nextjs-starter my-project
+cd my-project
+npm install
+```
+
+**Pros:**
+- ✅ Very fast
+- ✅ No git history
+- ✅ Popular in JS community
+- ✅ Works with GitHub/GitLab/Bitbucket
+
+**Cons:**
+- ❌ Requires GitHub
+- ❌ Requires internet
+
+---
+
+### 3. npm init / create Package (Most Professional)
+
+Create a package like `create-my-app`:
+
+**Setup:**
+```bash
+# Create a new package
+mkdir create-my-nextjs-app
+cd create-my-nextjs-app
+npm init -y
+
+# Add template files
+mkdir template
+cp -r ~/Projects/nextjs-starter/* template/
+
+# Create index.js that copies template
+# Publish to npm
+npm publish
+```
+
+**Usage:**
+```bash
+npm create my-nextjs-app my-project
+# or
+npx create-my-nextjs-app my-project
+```
+
+**Pros:**
+- ✅ Most professional
+- ✅ Like create-react-app, create-next-app
+- ✅ Can add interactive prompts
+- ✅ Versioned via npm
+- ✅ Can be private or public
+
+**Cons:**
+- ❌ More setup work
+- ❌ Requires npm registry
+- ❌ Overkill for personal use
+
+---
+
+### 4. Yeoman Generator (Old School but Powerful)
+
+```bash
+npm install -g yo generator-generator
+yo generator
+```
+
+**Pros:**
+- ✅ Very powerful
+- ✅ Interactive prompts
+- ✅ Conditional logic
+- ✅ File templating
+
+**Cons:**
+- ❌ Old technology (2012)
+- ❌ Feels outdated
+- ❌ Heavy dependency
+
+---
+
+### 5. Plop.js (Modern Alternative to Yeoman)
+
+```bash
+npm install --save-dev plop
+```
+
+**Pros:**
+- ✅ Modern
+- ✅ Micro-generator
+- ✅ Good for components
+- ✅ Used by many teams
+
+**Cons:**
+- ❌ More for components than full projects
+- ❌ Requires setup
+
+---
+
+## Recommendation
+
+### For Personal Use (Current)
+**Stick with simple copy** - it works, it's fast, and you don't need complexity.
+
+### For Team/Public Use
+**Use GitHub Template + create-next-app**:
+
+1. Push to GitHub once
+2. Enable template repository
+3. Use: `npx create-next-app my-app --example https://github.com/you/nextjs-starter`
+
+This is the **industry standard** and what most developers expect.
+
+### For Professional Product
+**Create npm package** (`create-my-app`):
+- Most professional
+- Versioned
+- Can be private
+- Like create-react-app
+
+---
+
+## About setup.sh
+
+The `setup.sh` script follows **standard bash practices**:
+
+- ✅ Shebang (`#!/bin/bash`)
+- ✅ Error handling (`set -e`)
+- ✅ Input validation
+- ✅ User feedback
+- ✅ Self-deletes after use (clean)
+- ✅ Cross-platform (macOS/Linux)
+
+This is similar to:
+- Ruby on Rails generators
+- Laravel artisan commands
+- Django management commands
+
+**It's not "off the cuff"** - it's a standard pattern for setup scripts.
+
+---
+
+## Comparison to Django Cookiecutter
+
+| Feature | Cookiecutter | GitHub Template | npm create |
+|---------|-------------|-----------------|------------|
+| **Templating** | Jinja2 | None | Custom |
+| **Prompts** | Yes | No | Yes (if custom) |
+| **Ecosystem** | Python | Git | JavaScript |
+| **Speed** | Medium | Fast | Fast |
+| **Complexity** | Medium | Low | High |
+| **Best For** | Python projects | Any project | JS projects |
+
+---
+
+## My Recommendation for You
+
+**Phase 1 (Now):** Keep the simple copy approach
+- It works
+- It's fast
+- No dependencies
+- Easy to maintain
+
+**Phase 2 (When sharing):** Push to GitHub as template
+- One-time setup
+- Use `create-next-app --example`
+- Industry standard
+- Easy for others
+
+**Phase 3 (If building product):** Create npm package
+- Professional
+- Versioned
+- Shareable
+- Like create-react-app
+
+---
+
+**Bottom line:** The current approach is fine for personal use. It's not "low-tech" - it's **pragmatic**. When you need to share it, upgrade to GitHub template. 🎯
--- a/COMPARISON.md
+++ b/COMPARISON.md
@ -0,0 +1,137 @@
+# Django Cookiecutter vs Next.js Starter
+
+## Side-by-Side Comparison
+
+### Django Cookiecutter Workflow
+
+```bash
+# Create new Django project
+cookiecutter ../django_starter/django_starter_cookiecutter
+
+# Answer prompts...
+# Install dependencies
+# Start development
+```
+
+### Next.js Starter Workflow
+
+```bash
+# Create new Next.js project
+npx degit ~/Projects/nextjs-starter my-new-project
+cd my-new-project
+./setup.sh
+
+# Answer prompts...
+# Dependencies auto-installed
+# Start development
+```
+
+## Feature Comparison
+
+| Feature | Django Cookiecutter | Next.js Starter |
+|---------|-------------------|-----------------|
+| **Speed** | ~30 seconds | ~20 seconds |
+| **Dependencies** | Python required | Node.js only |
+| **Template Updates** | Pull from cookiecutter | Pull from git |
+| **Customization** | Jinja2 templates | Direct file editing |
+| **Learning Curve** | Cookiecutter syntax | Standard git/npm |
+| **Ecosystem Fit** | Python-native | JavaScript-native |
+
+## Why This Approach for Next.js?
+
+### ✅ Advantages
+
+1. **Native to JavaScript ecosystem**
+   - No Python dependency
+   - Familiar to JS developers
+   - Uses standard npm/git tools
+
+2. **Simpler mental model**
+   - Just copy files
+   - No template syntax to learn
+   - Direct file editing
+
+3. **Faster**
+   - No template rendering
+   - Parallel operations
+   - Smaller footprint
+
+4. **More flexible**
+   - Easy to customize
+   - Can use GitHub templates
+   - Works with any git host
+
+### 🤔 Trade-offs
+
+1. **Less dynamic**
+   - No conditional file generation
+   - Manual search/replace for project name
+   - (But setup.sh handles this)
+
+2. **No validation**
+   - Cookiecutter can validate inputs
+   - (But less needed for simple projects)
+
+## Workflow Equivalence
+
+### Django: Create Project
+```bash
+cookiecutter ../django_starter/django_starter_cookiecutter
+cd my_django_project
+source venv/bin/activate
+pip install -r requirements.txt
+python manage.py migrate
+python manage.py runserver
+```
+
+### Next.js: Create Project
+```bash
+npx degit ~/Projects/nextjs-starter my-nextjs-project
+cd my-nextjs-project
+./setup.sh
+npm run dev
+```
+
+**Result**: Similar experience, native to each ecosystem!
+
+## When to Use Each
+
+### Use Django Cookiecutter When:
+- Building Python/Django projects
+- Need complex conditional logic
+- Want validated user inputs
+- Have many project variants
+
+### Use Next.js Starter When:
+- Building JavaScript/Next.js projects
+- Want simple, fast setup
+- Prefer standard tools
+- Need minimal dependencies
+
+## Updating Templates
+
+### Django Cookiecutter
+```bash
+cd django_starter_cookiecutter
+# Make changes
+# Regenerate projects manually
+```
+
+### Next.js Starter
+```bash
+cd ~/Projects/nextjs-starter
+# Make changes
+git add -A && git commit -m "Update template"
+
+# Update existing projects
+cd ~/Projects/my-project
+git remote add template ~/Projects/nextjs-starter
+git fetch template
+git merge template/main --allow-unrelated-histories
+```
+
+## Conclusion
+
+Both approaches are valid! The Next.js starter uses **JavaScript-native tools** (degit, npm, git) instead of Python-specific tools (cookiecutter), making it feel more natural in the JavaScript ecosystem.
+
+**Same philosophy, different implementation!** 🎯
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@ -0,0 +1,72 @@
+# Quick Start Guide
+
+## 🚀 Create a New Project (One Command)
+
+```bash
+# Copy template and run setup
+cp -r ~/Projects/nextjs-starter ~/Projects/my-new-project && cd ~/Projects/my-new-project && ./setup.sh
+```
+
+## 📦 What You Get
+
+- ✅ Next.js 16.0.7 (latest, security patched)
+- ✅ React 19.2.1 (latest, security patched)
+- ✅ Tailwind CSS v4 (latest)
+- ✅ TypeScript configured
+- ✅ shadcn/ui ready
+- ✅ ESLint configured
+- ✅ 0 vulnerabilities
+
+## 🎨 Add UI Components
+
+```bash
+# Add shadcn/ui components
+npx shadcn@latest add button
+npx shadcn@latest add card
+npx shadcn@latest add dialog
+npx shadcn@latest add input
+```
+
+## 🔧 Common Commands
+
+```bash
+npm run dev      # Start dev server (http://localhost:3000)
+npm run build    # Build for production
+npm start        # Start production server
+npm run lint     # Run ESLint
+```
+
+## 📁 Project Structure
+
+```
+my-new-project/
+├── src/
+│   ├── app/              # Pages and routes
+│   ├── components/ui/    # shadcn/ui components
+│   └── lib/              # Utilities
+├── package.json
+└── README.md
+```
+
+## 🎯 Next Steps
+
+1. **Customize metadata**: Edit `src/app/layout.tsx`
+2. **Change theme**: Edit `src/app/globals.css`
+3. **Add pages**: Create files in `src/app/`
+4. **Add components**: Use shadcn/ui or create your own
+
+## 💡 Tips
+
+- Use `cn()` utility for conditional classes
+- Environment variables: Create `.env.local`
+- Deploy to Vercel: `npx vercel`
+
+## 📚 Documentation
+
+- [Full Usage Guide](./USAGE.md)
+- [Next.js Docs](https://nextjs.org/docs)
+- [shadcn/ui Docs](https://ui.shadcn.com)
+
+---
+
+**That's it! You're ready to build. 🎉**
--- a/README.md
+++ b/README.md
@ -0,0 +1,149 @@
+# Next.js Starter Template
+
+A production-ready Next.js starter template with modern tooling and best practices.
+
+## 🚀 Quick Start
+
+```bash
+# Create new project
+cp -r ~/Projects/nextjs-starter ~/Projects/my-new-project
+cd ~/Projects/my-new-project
+./setup.sh
+
+# Start developing
+npm run dev
+```
+
+**That's it!** Open [http://localhost:3000](http://localhost:3000) 🎉
+
+## 📦 What's Included
+
+- ⚡️ **Next.js 16.0.7** - Latest with Turbopack & security patches
+- ⚛️ **React 19.2.1** - Latest with security patches (CVE-2025-55182)
+- 🎨 **Tailwind CSS v4** - Modern CSS with OKLCH colors
+- 🧩 **shadcn/ui** - Pre-configured, ready to use
+- 📝 **TypeScript** - Full type safety
+- 🎯 **ESLint** - Next.js recommended config
+- 🔒 **0 Vulnerabilities** - Fully patched and secure
+
+## 📚 Documentation
+
+- **[QUICKSTART.md](./QUICKSTART.md)** - Get started in 30 seconds
+- **[USAGE.md](./USAGE.md)** - Detailed usage guide
+- **[COMPARISON.md](./COMPARISON.md)** - vs Django Cookiecutter
+
+## 🎨 Adding Components
+
+```bash
+# Add shadcn/ui components
+npx shadcn@latest add button
+npx shadcn@latest add card
+npx shadcn@latest add dialog
+```
+
+## 📝 Available Scripts
+
+```bash
+npm run dev      # Development server
+npm run build    # Production build
+npm start        # Production server
+npm run lint     # Run ESLint
+```
+
+## 📁 Project Structure
+
+```
+nextjs-starter/
+├── src/
+│   ├── app/
+│   │   ├── globals.css      # Tailwind + theme
+│   │   ├── layout.tsx       # Root layout
+│   │   └── page.tsx         # Home page
+│   ├── components/ui/       # shadcn/ui components
+│   └── lib/utils.ts         # Utilities (cn helper)
+├── components.json          # shadcn/ui config
+├── setup.sh                 # Setup script
+└── README.md
+```
+
+## 🎯 Features
+
+### Modern Stack
+- Next.js 16 with Turbopack for fast builds
+- React 19 with latest features
+- Tailwind CSS v4 with modern CSS features
+- TypeScript for type safety
+
+### Developer Experience
+- Hot Module Replacement
+- Fast Refresh
+- TypeScript IntelliSense
+- ESLint integration
+
+### Production Ready
+- Optimized builds
+- Security patches applied
+- Zero vulnerabilities
+- Best practices configured
+
+### Customizable
+- Clean, neutral theme
+- OKLCH color system
+- Dark mode ready
+- Easy to customize
+
+## 🔒 Security
+
+This template includes the latest security patches:
+- **CVE-2025-66478** (Next.js) - Patched in 16.0.7
+- **CVE-2025-55182** (React) - Patched in 19.2.1
+
+## 🚀 Deployment
+
+### Vercel (Recommended)
+```bash
+npm install -g vercel
+vercel
+```
+
+### Other Platforms
+```bash
+npm run build
+npm start
+```
+
+## 💡 Tips
+
+1. **Use the `cn` utility** for conditional classes
+2. **Create `.env.local`** for environment variables
+3. **Organize components** in `src/components/`
+4. **Use TypeScript** for better DX
+
+## 📖 Learn More
+
+- [Next.js Documentation](https://nextjs.org/docs)
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [shadcn/ui Documentation](https://ui.shadcn.com)
+- [React Documentation](https://react.dev)
+
+## 🤝 Similar to Django Cookiecutter
+
+This template provides the same quick-start experience as your Django cookiecutter, but uses JavaScript-native tools:
+
+```bash
+# Django
+cookiecutter ../django_starter/django_starter_cookiecutter
+
+# Next.js (equivalent)
+cp -r ~/Projects/nextjs-starter ~/Projects/my-project && cd ~/Projects/my-project && ./setup.sh
+```
+
+See [COMPARISON.md](./COMPARISON.md) for detailed comparison.
+
+## 📄 License
+
+MIT License - use freely for any project!
+
+---
+
+**Happy coding! 🎉**
--- a/USAGE.md
+++ b/USAGE.md
@ -0,0 +1,243 @@
+# 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)
--- a/components.json
+++ b/components.json
@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;
--- a/next-env.d.ts
+++ b/next-env.d.ts
@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
--- a/next.config.ts
+++ b/next.config.ts
@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;
--- a/package.json
+++ b/package.json
@ -0,0 +1,32 @@
+{
+  "name": "nextjs-starter",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@radix-ui/react-slot": "^1.2.4",
+    "@tailwindcss/postcss": "^4.1.17",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.554.0",
+    "next": "^16.0.7",
+    "postcss": "^8.5.6",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss": "^4.1.17"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "^16.0.7",
+    "typescript": "^5"
+  }
+}
--- a/postcss.config.mjs
+++ b/postcss.config.mjs
@ -0,0 +1,6 @@
+const config = {
+    plugins: {
+        "@tailwindcss/postcss": {},
+    },
+};
+export default config;
--- a/setup.sh
+++ b/setup.sh
@ -0,0 +1,66 @@
+#!/bin/bash
+
+# Next.js Starter Setup Script
+# This script will delete itself after running
+
+set -e
+
+echo "🚀 Setting up your Next.js project..."
+echo ""
+
+# Check if package.json exists
+if [ ! -f "package.json" ]; then
+    echo "❌ Error: package.json not found. Are you in the right directory?"
+    exit 1
+fi
+
+# Get project name from user
+read -p "📝 Enter your project name (default: my-nextjs-app): " PROJECT_NAME
+PROJECT_NAME=${PROJECT_NAME:-my-nextjs-app}
+
+# Validate project name (alphanumeric, hyphens, underscores only)
+if ! [[ "$PROJECT_NAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    echo "❌ Error: Project name can only contain letters, numbers, hyphens, and underscores"
+    exit 1
+fi
+
+# Update package.json with new project name
+echo "📦 Updating package.json..."
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    # macOS
+    sed -i '' "s/\"name\": \"nextjs-starter\"/\"name\": \"$PROJECT_NAME\"/" package.json
+else
+    # Linux
+    sed -i "s/\"name\": \"nextjs-starter\"/\"name\": \"$PROJECT_NAME\"/" package.json
+fi
+
+# Install dependencies
+echo ""
+echo "📥 Installing dependencies..."
+npm install
+
+# Initialize git if not already initialized
+if [ ! -d ".git" ]; then
+    echo ""
+    echo "🔧 Initializing git repository..."
+    git init
+    git add .
+    git commit -m "Initial commit from nextjs-starter template"
+fi
+
+echo ""
+echo "✅ Setup complete!"
+echo ""
+echo "🎉 Your project '$PROJECT_NAME' is ready!"
+echo ""
+echo "Next steps:"
+echo "  1. Run 'npm run dev' to start the development server"
+echo "  2. Add shadcn/ui components: 'npx shadcn@latest add button'"
+echo "  3. Start building your app!"
+echo ""
+
+# Self-destruct: Remove this setup script
+echo "🗑️  Removing setup script..."
+rm -- "$0"
+
+echo "✨ All done!"
--- a/src/app/globals.css
+++ b/src/app/globals.css
@ -0,0 +1,102 @@
+@import "tailwindcss";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+}
+
+:root {
+  --radius: 0.5rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.15 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.15 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.15 0 0);
+  --primary: oklch(0.18 0 0);
+  --primary-foreground: oklch(1 0 0);
+  --secondary: oklch(0.95 0 0);
+  --secondary-foreground: oklch(0.18 0 0);
+  --muted: oklch(0.96 0 0);
+  --muted-foreground: oklch(0.50 0 0);
+  --accent: oklch(0.94 0 0);
+  --accent-foreground: oklch(0.18 0 0);
+  --destructive: oklch(0.55 0.22 25);
+  --border: oklch(0.90 0 0);
+  --input: oklch(0.95 0 0);
+  --ring: oklch(0.18 0 0);
+  --chart-1: oklch(0.45 0.15 250);
+  --chart-2: oklch(0.55 0.15 160);
+  --chart-3: oklch(0.50 0.15 30);
+  --chart-4: oklch(0.60 0.12 140);
+  --chart-5: oklch(0.50 0.18 320);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  html {
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  }
+}
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@ -0,0 +1,19 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Next.js Starter",
+  description: "A modern Next.js starter with Tailwind CSS and shadcn/ui",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@ -0,0 +1,33 @@
+export default function Home() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center p-24">
+      <main className="flex flex-col items-center gap-8 text-center">
+        <h1 className="text-4xl font-bold tracking-tight">
+          Next.js Starter Template
+        </h1>
+        <p className="text-lg text-muted-foreground max-w-2xl">
+          A production-ready starter with Next.js 16, React 19, Tailwind CSS v4, and shadcn/ui.
+          Start building your next project with modern tools and best practices.
+        </p>
+        <div className="flex gap-4">
+          <a
+            href="https://nextjs.org/docs"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="rounded-lg bg-primary px-6 py-3 text-primary-foreground hover:bg-primary/90 transition-colors"
+          >
+            Read the docs
+          </a>
+          <a
+            href="https://ui.shadcn.com"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="rounded-lg border border-border px-6 py-3 hover:bg-accent transition-colors"
+          >
+            shadcn/ui
+          </a>
+        </div>
+      </main>
+    </div>
+  );
+}
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
--- a/tsconfig.json
+++ b/tsconfig.json
@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}