Getting Started with Next.js 16: A Beginner's Guide for Vibe Coders

Next.js is a React framework for building full-stack web applications. It gives you file-based routing, server rendering, backend API endpoints, image optimization and SEO tools out of the box. It's also the framework AI coding agents reach for most often when you ask them to "build a web app", so understanding the basics makes you a much better vibe coder: you'll know what your agent is building and be able to prompt it precisely.

This guide covers Next.js 16 (the current version is 16.3, released August 2026).

What Next.js gives you

• File-based routing: folders in app/ become URLs. See our routing guide.
• Server Components by default: pages render on the server, so they're fast and SEO-friendly.
• Route Handlers: build API endpoints next to your pages. See Next.js API routes.
• Proxy (formerly middleware): run code before requests, for things like auth redirects. See Next.js proxy.
• Built-in SEO: the Metadata API, sitemaps and Open Graph images.
• Image optimization: the Image component serves modern formats at the right size.
• Turbopack: the default bundler since Next.js 16, with much faster dev and build times.

Install Next.js

You need Node.js↗ (opens in a new tab) 20.9 or newer. Then run:

npx create-next-app@latest my-app
cd my-app
npm run dev

The installer asks a few questions. The recommended defaults (TypeScript, a linter, Tailwind CSS, the App Router and Turbopack) are a good choice, especially for vibe coding, because they're the most common setup and AI models know them well.

Open http://localhost:3000 in your browser and you'll see your app.

Set up your project for AI agents

Next.js 16.2+ ships its documentation inside the next package, and running next dev maintains a block in an AGENTS.md file that tells coding agents to read those version-matched docs. This matters because AI models are often trained on older Next.js versions and will otherwise use outdated APIs.

Commit that AGENTS.md file, and add your own project notes below it. Our guide to AGENTS.md and AI context files explains what to include.

Project structure

my-app/
├── app/
│   ├── layout.tsx     # Shared shell for every page
│   ├── page.tsx       # The home page at /
│   └── globals.css
├── public/            # Static files (images, favicon)
├── AGENTS.md          # Instructions for AI coding agents
├── next.config.ts
└── package.json

Most of your work happens in app/.

Create your first page

To add an About page, create app/about/page.tsx:

export const metadata = {
  title: 'About us',
  description: 'Learn more about our team and mission.',
};

export default function AboutPage() {
  return (
    <main className="mx-auto max-w-2xl p-8">
      <h1 className="text-4xl font-bold">About us</h1>
      <p className="mt-4">Welcome to our about page!</p>
    </main>
  );
}

It's now live at /about. The metadata export sets the page title and description for search engines.

Server Components vs Client Components

By default, every component in app/ is a Server Component: it runs on the server, can fetch data directly, and sends zero JavaScript to the browser for itself.

When you need interactivity (state, event handlers, browser APIs), add 'use client' at the top of the file to make a Client Component:

'use client';

import { useState } from 'react';

export default function LikeButton() {
  const [likes, setLikes] = useState(0);
  return (
    <button onClick={() => setLikes(likes + 1)} className="rounded bg-black px-4 py-2 text-white">
      ♥ {likes}
    </button>
  );
}

Use it from a Server Component like any other component. A good rule: keep 'use client' components small and at the "leaves" of your component tree.

Fetching data

In a Server Component, you can make the component async and fetch directly:

type Post = { id: number; title: string };

export default async function PostsPage() {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts?_limit=5');
  const posts: Post[] = await res.json();

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

No useEffect, no loading spinners to wire up by hand, and your API keys stay on the server. Add a loading.tsx file next to the page to show a loading state while data streams in.

For writing data (forms, mutations), use Server Actions or Route Handlers.

Styling with Tailwind CSS

If you chose Tailwind during setup, use utility classes directly:

<h1 className="text-4xl font-bold tracking-tight text-gray-900">Hello, Next.js!</h1>

Tailwind is also the styling approach AI agents handle best, which is another reason it's a great default for vibe coding.

Deploy your app

The easiest option is Vercel↗ (opens in a new tab), made by the creators of Next.js:

1. Push your project to GitHub (new to Git? See Git for vibe coders).
2. Import the repository on Vercel.
3. Add any environment variables (never commit secrets to Git).
4. Click deploy. Every future push deploys automatically.

Next.js also runs on Netlify, Cloudflare, AWS, a Docker container or any Node.js server.

Vibe coding a Next.js app

Here's a prompt that works well with agents like Claude Code or Cursor once your project exists:

Read AGENTS.md first. Add a /blog section to this Next.js 16 app:
- Posts are MDX files in content/blog with title, date and description frontmatter
- /blog lists posts newest first; /blog/[slug] renders a post
- Use generateStaticParams so posts are prerendered
- Add metadata (title, description, canonical URL) for every page
Show me a plan before writing code.

For a complete project walkthrough, follow build and deploy a full-stack app with AI.

Next steps

1. Routing: dynamic routes and route groups
2. API Route Handlers
3. Image optimization
4. SEO with the Metadata API
5. Proxy (middleware) and authentication

The official Next.js documentation↗ (opens in a new tab) and Learn Next.js course↗ (opens in a new tab) are excellent next resources.

Frequently asked questions

Do I need to know React before learning Next.js?

Basic React (components, props, state) helps a lot. But you can learn both together, especially with an AI agent explaining the code it writes.

Should I use TypeScript or JavaScript?

TypeScript. AI agents write better code when types tell them what data looks like, and type errors catch many AI mistakes before you run the app.

Is Next.js free?

Yes, Next.js is open source and free. Hosting can be free for small projects on Vercel's Hobby plan and similar tiers.