Building Your First Next.js Application: A Complete Beginner's Guide

Introduction

Next.js has revolutionized the way we build web applications. Whether you're creating a simple blog like this one or a complex web application, Next.js provides the tools and features to build fast, production-ready applications with an amazing developer experience.

In this guide, we'll walk through building your first Next.js application from scratch. By the end, you'll understand the core concepts and be ready to build your own projects.

What is Next.js?

Next.js is a React framework that gives you building blocks to create web applications. It handles the tooling and configuration needed for React, and provides additional structure, features, and optimizations for your application.

Key features include:

• Server-Side Rendering (SSR) - Pages are rendered on the server for better performance and SEO
• Static Site Generation (SSG) - Pre-render pages at build time
• File-based Routing - Create routes by adding files to the pages or app directory
• API Routes - Build your API endpoints within your Next.js app
• Automatic Code Splitting - Only load the JavaScript needed for each page
• Built-in CSS Support - Import CSS and CSS Modules directly

Prerequisites

Before we begin, make sure you have:

• Node.js 18.17 or later installed
• A code editor (VS Code recommended)
• Basic knowledge of JavaScript and React
• Familiarity with the command line

Setting Up Your First Next.js Project

Let's create a new Next.js application using the official create-next-app tool.

Step 1: Create the Project

Open your terminal and run:

npx create-next-app@latest my-first-app

You'll be asked several questions. Here are the recommended settings for beginners:

• Would you like to use TypeScript? Yes ✅
• Would you like to use ESLint? Yes ✅
• Would you like to use Tailwind CSS? Yes ✅
• Would you like to use the App Router? Yes ✅
• Would you like to customize the default import alias? No

Step 2: Navigate to Your Project

cd my-first-app

Step 3: Start the Development Server

npm run dev

Visit http://localhost:3000 in your browser, and you'll see your new Next.js application running!

Understanding the Project Structure

Let's explore the important files and folders:

app/ - Contains your application routes and layouts

• layout.tsx - Root layout for your entire app
• page.tsx - Home page component
• globals.css - Global styles

public/ - Static assets like images and fonts

package.json - Project dependencies and scripts

next.config.ts - Next.js configuration

tailwind.config.ts - Tailwind CSS configuration

Creating Your First Page

Next.js uses a file-based routing system. Let's create an "About" page.

Step 1: Create the About Page

Create a new file: app/about/page.tsx

export default function About() {
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="max-w-2xl mx-auto p-8">
        <h1 className="text-4xl font-bold mb-4">About Us</h1>
        <p className="text-lg text-gray-600">
          Welcome to my first Next.js application! 
          This page was created using Next.js 15 and Tailwind CSS.
        </p>
      </div>
    </div>
  )
}

Now visit http://localhost:3000/about to see your new page!

Building a Simple Component

Let's create a reusable button component.

Step 1: Create Components Folder

Create app/components/Button.tsx

interface ButtonProps {
  text: string
  onClick?: () => void
  variant?: 'primary' | 'secondary'
}

export default function Button({ 
  text, 
  onClick, 
  variant = 'primary' 
}: ButtonProps) {
  const baseClasses = 'px-6 py-3 rounded-lg font-semibold transition-colors'
  const variantClasses = {
    primary: 'bg-purple-600 text-white hover:bg-purple-700',
    secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300'
  }

  return (
    <button 
      onClick={onClick}
      className={`${baseClasses} ${variantClasses[variant]}`}
    >
      {text}
    </button>
  )
}

Step 2: Use the Component

Update your app/page.tsx:

import Button from './components/Button'

export default function Home() {
  return (
    <main className="min-h-screen flex flex-col items-center justify-center p-8">
      <h1 className="text-5xl font-bold mb-8">
        Welcome to Next.js!
      </h1>
      <div className="flex gap-4">
        <Button text="Get Started" variant="primary" />
        <Button text="Learn More" variant="secondary" />
      </div>
    </main>
  )
}

Adding Metadata for SEO

Next.js makes SEO easy with built-in metadata support.

Update your app/about/page.tsx:

import { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'About Us | My First App',
  description: 'Learn more about our Next.js application',
}

export default function About() {
  return (
    // ... your existing code
  )
}

Styling with Tailwind CSS

Tailwind CSS is already set up in your project. Here are some useful utility classes:

Layout:

• flex, grid - Flexbox and Grid layouts
• min-h-screen - Minimum height of viewport
• max-w-2xl, mx-auto - Max width with centered margins

Spacing:

• p-8 - Padding of 2rem (32px)
• mb-4 - Margin bottom of 1rem (16px)
• gap-4 - Gap of 1rem in flex/grid containers

Typography:

• text-4xl - Font size 2.25rem (36px)
• font-bold - Bold font weight
• text-gray-600 - Gray color at 60% opacity

Colors:

• bg-purple-600 - Background purple
• text-white - White text
• hover:bg-purple-700 - Darker purple on hover

Deploying Your Application

Step 1: Push to GitHub

Create a new repository on GitHub and push your code:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin your-repo-url
git push -u origin main

Step 2: Deploy to Vercel

1. Go to vercel.com
2. Sign up with GitHub
3. Click "New Project"
4. Import your repository
5. Click "Deploy"

That's it! Your app will be live in minutes.

Next Steps

Now that you've built your first Next.js application, here are some next steps:

1. Add Dynamic Routes - Learn about [id] folder syntax for dynamic pages
2. Fetch Data - Use fetch in Server Components for data fetching
3. Add a Database - Connect to PostgreSQL, MongoDB, or use Sanity CMS
4. Implement Authentication - Use NextAuth.js or Clerk
5. Build an API - Create API routes in the app/api folder

Common Pitfalls to Avoid

1. Forgetting to Mark Client Components If you use hooks like useState or useEffect, add 'use client' at the top of your file.

2. Not Optimizing Images Always use Next.js <Image> component instead of <img> for better performance.

3. Ignoring TypeScript Errors TypeScript catches bugs before they happen. Don't ignore the red squiggly lines!

4. Not Using Environment Variables Never commit API keys. Use .env.local for sensitive data.

Conclusion

Congratulations! You've just built your first Next.js application. You've learned about:

• Setting up a Next.js project
• Creating pages and components
• Using Tailwind CSS for styling
• Adding metadata for SEO
• Deploying to production

Next.js is a powerful framework with much more to explore. Keep building, keep learning, and most importantly, have fun creating amazing web applications!