Getting Started: Build a Next.js App Locally and Ship Hello World

This post is for anyone who is new to Next.js. In about 10 minutes, you will create a project on your machine, write a Hello World page, and see it running in the browser.

Prerequisites

Before you start, make sure Node.js is installed.

Open a terminal (Terminal on macOS / Linux, PowerShell or CMD on Windows) and run:

node -v
npm -v

Expected output (versions may differ — anything v18 or higher is fine):

v20.11.0
10.2.4

If you get "command not found", Node.js is not installed yet. Download the LTS version from nodejs.org and install it with the default options.

Step 1: Scaffold the Project with npx

npx ships with npm and lets you run command-line tools without installing them globally. We will use the official create-next-app scaffolder:

cd ~/Desktop
npx create-next-app@latest my-blog --yes

The --yes flag accepts the default options:

• TypeScript enabled
• Tailwind CSS enabled
• ESLint enabled
• App Router enabled
• No src directory
• Path alias @/*

Wait a minute or two. Once you see "Success!", you are done.

Step 2: Start the Dev Server

cd my-blog
npm run dev

Expected output:

▲ Next.js 15.x.x
- Local:  http://localhost:3000
- Ready in 2.1s

Open http://localhost:3000 in your browser. You should see the default Next.js welcome page.

Step 3: Replace It with Hello World

Open app/page.tsx and replace the entire file with:

export default function Home() {
  return (
    <main className="min-h-screen flex items-center justify-center bg-neutral-950 text-neutral-100">
      <div className="text-center">
        <h1 className="text-5xl font-bold mb-4 text-emerald-400">
          Hello World
        </h1>
        <p className="text-neutral-400">
          My first Next.js page
        </p>
      </div>
    </main>
  );
}

Save the file. The browser will hot-reload, and you will see a black page with green Hello World in the middle.

Step 4: Add Another Page

Next.js routing is file-based. To add a /blog page, just create a folder and a file:

mkdir -p app/blog
touch app/blog/page.tsx

Contents of app/blog/page.tsx:

import Link from 'next/link';

export default function BlogPage() {
  return (
    <main className="min-h-screen bg-neutral-950 text-neutral-100 p-8">
      <div className="max-w-2xl mx-auto">
        <Link href="/" className="text-emerald-400 hover:underline text-sm">
          ← Back to home
        </Link>
        <h1 className="text-4xl font-bold mt-6 mb-8">Blog</h1>
        <p className="text-neutral-400">
          This is the blog index page.
        </p>
      </div>
    </main>
  );
}

Visit http://localhost:3000/blog — the new page will be there.

Step 5: Add a Link from the Home Page

Go back to app/page.tsx and add a button:

import Link from 'next/link';

export default function Home() {
  return (
    <main className="min-h-screen flex items-center justify-center bg-neutral-950 text-neutral-100">
      <div className="text-center">
        <h1 className="text-5xl font-bold mb-4 text-emerald-400">
          Hello World
        </h1>
        <p className="text-neutral-400 mb-6">
          My first Next.js page
        </p>
        <Link
          href="/blog"
          className="inline-block px-4 py-2 bg-emerald-500 text-neutral-950 rounded-md hover:bg-emerald-400 transition-colors"
        >
          View blog →
        </Link>
      </div>
    </main>
  );
}

Click the button — you will land on /blog.

Project Structure

After finishing, your project should look roughly like this:

my-blog/
├── app/
│   ├── layout.tsx          ← Root layout
│   ├── page.tsx            ← Home page (Hello World)
│   ├── globals.css         ← Global styles
│   └── blog/
│       └── page.tsx        ← Blog page
├── package.json
├── next.config.ts
└── tsconfig.json

Common Commands

Command	What it does
npm run dev	Start the dev server (hot reload)
npm run build	Build a production bundle
npm run start	Run the production build
npm run lint	Lint the code

During development, you will almost only use npm run dev.

Troubleshooting

Port 3000 is Already in Use

If port 3000 is taken, Next.js automatically switches to 3001 and prints:

- Local:  http://localhost:3001

Page Does Not Update After Edits

First, check the terminal for errors. If it says "Compiled successfully", hard-refresh the browser (Cmd+R on macOS, Ctrl+R on Windows).

Stop the Dev Server

Press Ctrl+C in the terminal.

Slow npm Downloads

Switch to a faster mirror:

npm config set registry https://registry.npmmirror.com

What's Next

Once this minimal example works, you can move on to:

• Writing posts in Markdown and parsing frontmatter with gray-matter
• Adding Supabase for data and authentication
• Adding SEO metadata and Open Graph tags
• Deploying to Vercel with a single command

Summary

• One command scaffolds the project: npx create-next-app
• One command starts the dev server: npm run dev
• Next.js routing is file-based — adding a file adds a route
• One page.tsx equals one page

The whole process takes less than 10 minutes. This minimal structure is the foundation for every Next.js project you build from here on.