A Comprehensive Guide to Installing Next.js

Maria
CSS
01 Aug, 2026

Next.js has emerged as a powerful framework for building React applications, offering features like server-side rendering, static site generation, and API routes. If you're looking to get started with Next.js, this guide will walk you through the installation process, ensuring you have everything you need to create your first application.

Understanding System Requirements

Before diving into the installation, it's crucial to ensure that your development environment meets the necessary requirements. Here’s what you need:

Node.js Version: Ensure you have at least version 20.9 of Node.js installed. This is essential for running Next.js smoothly.

Operating Systems: Next.js is compatible with various operating systems, including macOS, Windows (including WSL), and Linux.

Supported Browsers

Next.js supports modern browsers without requiring additional configuration. The following browsers are fully supported:

Google Chrome: Version 111 and above
Microsoft Edge: Version 111 and above
Mozilla Firefox: Version 111 and above
Safari: Version 16.4 and above

For more details on browser compatibility and how to configure polyfills, refer to the official Next.js documentation.

Creating a New Next.js Application

The easiest way to set up a new Next.js application is by using the command-line interface (CLI). This method automates the setup process, allowing you to focus on building your application.

Using the CLI

To create a new Next.js app, follow these steps:

Open your terminal.
Run the following command to create a new Next.js application named my-app:

pnpm create next-app@latest my-app --yes

Navigate into your project directory:

cd my-app

Start the development server:

pnpm dev

Open your browser and visit localhost:3000 to see your new application in action.

The yes flag allows you to skip prompts by using default settings, which include TypeScript, Tailwind CSS, ESLint, and the App Router.

Customizing Your Installation

If you prefer to customize your installation, you can do so by running the command without the --yes flag. You will be prompted to make several choices regarding your project setup, including:

Project name
Use of TypeScript
Choice of linter (ESLint or Biome)
Inclusion of Tailwind CSS
Directory structure preferences

This flexibility allows you to tailor your Next.js application to your specific needs.

Manual Installation

If you prefer a more hands-on approach, you can manually install Next.js and its dependencies. Here’s how:

Create a new directory for your project and navigate into it:

mkdir my-app
cd my-app

Install the required packages:

pnpm i next@latest react@latest react-dom@latest

Update your package.json file to include the following scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}

These scripts will help you manage different stages of your application development, including starting the development server, building for production, and running lint checks.

Setting Up Your Project Structure

Next.js utilizes a file-system-based routing system, meaning the structure of your files determines the routes in your application. Here’s how to set up your project structure:

Creating the app Directory

Create an app directory at the root of your project.
Inside the app directory, create a layout.tsx file. This file serves as the root layout and must include the html and body tags:

tsx;
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Next, create a home page by adding an app/page.tsx file with the following content:

export default function Page() {
  return <h1>Hello, Next.js!</h1>;
}

When users visit the root of your application (/), both layout.tsx and page.tsx will be rendered.

Optional: Creating a public Folder

To store static assets like images and fonts, you can create a public folder at the root of your project. Files in this folder can be accessed directly from the base URL. For example, if you have an image named profile.png, you can reference it in your code like this:

import Image from "next/image";

export default function Page() {
  return <Image src="/profile.png" alt="Profile" width={100} height={100} />;
}

Running the Development Server

To see your application in action, follow these steps:

Start the development server by running:

npm run dev

Open your web browser and navigate to localhost:3000 to view your application.
Edit the app/page.tsx file and save your changes to see the updates reflected in real-time.

Setting Up TypeScript

Next.js comes with built-in support for TypeScript. To add TypeScript to your project, simply rename a file to have a .ts or .tsx extension and run the development server. Next.js will automatically install the necessary dependencies and create a tsconfig.json file with recommended configurations.

IDE Plugin

For enhanced type-checking and auto-completion, you can enable the custom TypeScript plugin in your code editor. For example, in Visual Studio Code, you can do this by:

Opening the command palette (Ctrl/⌘ + Shift + P)
Searching for "TypeScript: Select TypeScript Version"
Choosing "Use Workspace Version"

Setting Up Linting

Next.js supports linting through ESLint or Biome. You can choose your preferred linter and run it via the scripts defined in your package.json. Here’s how to set it up:

Using ESLint

If you opt for ESLint, include the following in your package.json:

{
  "scripts": {
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}

Using Biome

If you prefer Biome, you can set it up like this:

{
  "scripts": {
    "lint": "biome check",
    "format": "biome format --write"
  }
}

If you previously used next lint, you can migrate your scripts to the ESLint CLI using the codemod:

npx @next/codemod@canary next-lint-to-eslint-cli .

Configuring Absolute Imports and Module Path Aliases

Next.js supports absolute imports and module path aliases, making it easier to manage your imports. To set this up, modify your tsconfig.json or jsconfig.json file to include the following:

{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/components/*": ["components/*"],
      "@/styles/*": ["styles/*"]
    }
  }
}

This configuration allows you to import components more cleanly, for example:

import { Button } from "@/components/button";

Frequently Asked Questions

You need a supported version of Node.js and a package manager such as npm, pnpm, Yarn, or Bun. Once those are installed, you can create a project with the create-next-app command.

Next.js works with npm, pnpm, Yarn, and Bun. Choose the package manager your team already uses; pnpm is a popular choice for its efficient disk usage and fast installs.

Yes. Install next, react, and react-dom, add the required Next.js scripts to package.json, then create an app or pages directory. For a larger existing app, migrate one route at a time and test each step.

TypeScript is optional, but it is a strong default for most projects because it catches many errors before runtime and improves editor autocomplete. You can also add it later by creating a .ts or .tsx file.

First, make sure the development server is still running and check the terminal for errors. If port 3000 is already in use, Next.js will usually offer another port; open the URL shown in the terminal instead.

Conclusion

Installing Next.js is a straightforward process that opens up a world of possibilities for building modern web applications. By following the steps outlined in this guide, you can set up your development environment, create a new application, and start building with confidence. Whether you choose to use the CLI for a quick setup or prefer a manual installation, Next.js provides the flexibility and power needed to create robust applications. Happy coding!