📖 Introduction

Welcome to this comprehensive guide on installing and setting up a Next.js project from scratch! Whether you're a beginner starting your React journey or an experienced developer exploring Next.js for the first time, this tutorial will walk you through every step needed to get a production-ready environment running.

By the end of this tutorial, you'll understand how to install Node.js, choose the right package manager, scaffold a new project, understand the resulting folder structure, configure essential tools, and run your app in both development and production modes. 🚀

💻 System Requirements

Before installing anything, make sure your machine meets the minimum requirements for running a modern Next.js application.

⚙️ Installing Node.js

Node.js is the JavaScript runtime that powers the entire tooling ecosystem around Next.js. There are several ways to install it.

node -v
npm -v

📦 Understanding Package Managers

A package manager handles installing, updating, and managing the JavaScript dependencies your project relies on. Next.js is compatible with several popular options, each with its own trade-offs in speed, disk usage, and features.

npm

npm is the default package manager bundled with Node.js. It's the most widely used and has the largest ecosystem support.

npm install react

Yarn

Yarn was created to improve on early npm limitations, offering faster installs and a reliable lockfile system.

yarn add react

pnpm

pnpm uses a content-addressable storage system, meaning packages are stored once on disk and linked across projects — saving significant disk space.

pnpm add react

Bun

Bun is an all-in-one JavaScript runtime and package manager known for its exceptional speed, thanks to being built on a low-level engine rather than JavaScript itself.

bun add react

npx create-next-app@latest

yarn create next-app

pnpm create next-app

bun create next-app

🏗️ Creating a Next.js Project

Now that Node.js and a package manager are ready, it's time to scaffold your first Next.js project.

Using create-next-app

The official and recommended way to start a new Next.js project is via the create-next-app CLI tool, which sets up everything automatically.

npx create-next-app@latest my-app

You'll be prompted with several configuration questions:

Manual Installation

For full control, you can set up a Next.js project manually without the CLI scaffolding tool.

mkdir my-app && cd my-app
npm init -y
npm install next react react-dom

Then add the following scripts to your package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Choosing the App Router

The App Router, introduced in Next.js 13, is built on React Server Components and is the modern, recommended approach going forward.

Choosing the Pages Router (Legacy)

The Pages Router is the original Next.js routing system, still supported for backward compatibility.

🗂️ Project Structure

Understanding the generated folder structure helps you navigate and extend your project confidently.

The app Directory

The app directory is the heart of the App Router. Each folder inside it maps directly to a route segment, and special files like page.tsx and layout.tsx define what renders at that route.

The public Directory

Static assets such as images, fonts, and icons live in the public directory. Files here are served from the root URL path.

The src Directory

Optionally, you can place your app directory (and other source code) inside a top-level src folder to keep configuration files cleanly separated from application code.

🔧 Configuration Files

Next.js relies on several configuration files to customize build behavior, linting, styling, and type checking.

next.config.ts

This file allows you to customize build-time and runtime behavior of your Next.js app.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactStrictMode: true,
};

export default nextConfig;

TypeScript Setup

If enabled during scaffolding, Next.js automatically generates a tsconfig.json and installs the necessary type definitions.

npm install --save-dev typescript @types/react @types/node

ESLint Setup

ESLint helps catch bugs and enforce consistent code style. Next.js ships with a built-in ESLint configuration tailored for React and Next.js projects.

npm run lint

Tailwind CSS Setup

Tailwind CSS is a utility-first CSS framework that integrates seamlessly with Next.js when selected during setup.

@tailwind base;
@tailwind components;
@tailwind utilities;

Environment Variables

Environment variables allow you to store secrets and configuration outside your codebase. Next.js automatically loads variables from .env.local.

DATABASE_URL="postgres://user:pass@localhost:5432/db"
NEXT_PUBLIC_API_URL="https://api.example.com"

🚦 Running the Development Server

Once your project is set up, start the local development server to preview your app with hot reloading enabled.

npm run dev

By default, your application will be available at http://localhost:3000.

📦 Building for Production

Before deploying, you must create an optimized production build of your application.

npm run build

Starting the Production Server

After building, launch the production server with the following command:

npm run start

🛠️ Development Workflow

A smooth development workflow relies on the right set of tools to inspect, debug, and monitor your application.

React Developer Tools

The React Developer Tools browser extension lets you inspect the component tree, props, and state directly in your browser's dev tools panel.

Next.js Developer Tools

Next.js includes built-in overlays for error reporting, build diagnostics, and performance insights during development.

Updating Next.js

Keeping Next.js up to date ensures access to the latest features, performance improvements, and security patches.

npm install next@latest react@latest react-dom@latest

❗ Common Installation Issues

Even with careful setup, a few recurring issues tend to trip up newcomers.

Troubleshooting

# Run on a different port
npm run dev -- -p 3001

# Clear cache and reinstall
rm -rf .next node_modules
npm install

✅ Best Practices

🎯 Summary

You're now fully equipped to start building with Next.js! From here, the next step is diving into routing, data fetching, and component architecture. Happy coding! 🎉