Next.js Setup

Requirements Before You Start

Next.js requires a recent version of Node.js (Node 18.18 or later is required by modern Next.js releases, with Node 20+ recommended) and works with npm, yarn, pnpm, or bun as a package manager. You do not need to install Next.js globally — each project manages its own local copy via package.json.

For editing, Visual Studio Code (or an editor with equivalent TypeScript support, such as Cursor) is recommended because Next.js and its official templates ship with strong TypeScript support out of the box, giving you autocomplete for routes, props, and configuration.

node -v
# v20.11.0 (or newer)

npm -v
# 10.x or newer

Always confirm your Node.js version before starting a new project — an outdated Node version is the most common cause of confusing install errors.

Checking and Installing Node.js

# check your current version
node -v

# install/manage versions with nvm (recommended)
nvm install 20
nvm use 20

• Use a version manager like nvm (macOS/Linux) or fnm/nvs (Windows) to switch Node versions per project.
• Next.js checks your Node version at build time and will error clearly if it is too old.
• You do not need a global Next.js install; npx create-next-app downloads it temporarily.
• TypeScript is optional but strongly recommended and is the default in create-next-app.

Setup Cheat Sheet

Everything you need installed before creating your first project.

Recommended Editor Configuration

Next.js projects benefit from ESLint (configured automatically by create-next-app) to catch common mistakes, and from your editor's built-in TypeScript server to surface type errors for props, route params, and API responses as you type.

• Enable "Format on Save" with Prettier or your editor's built-in formatter.
• Install the ESLint extension so lint errors from next lint show up inline.
• Install React Developer Tools in your browser to inspect Server/Client Component boundaries.

Files a Fresh Project Includes

A newly scaffolded Next.js project comes with a small set of configuration files in addition to your app/ directory. Understanding what each one does upfront prevents confusion later when you need to customize the build.

Common Mistakes

• Using a Node.js version older than what the installed Next.js release requires.
• Installing Next.js globally and wondering why project-local versions don't match.
• Ignoring ESLint warnings that catch real bugs, like missing dependency arrays.
• Committing .next/ or node_modules/ because .gitignore was edited or missing.

Key Takeaways

• Next.js requires Node.js 18.18+ (20+ recommended); check with node -v before starting.
• You never need to install Next.js globally — npx create-next-app handles it per project.
• A code editor with TypeScript support significantly improves the Next.js development experience.
• Fresh projects include package.json, next.config.js, and tsconfig.json by default.
• Keep node_modules/ and .next/ out of version control via .gitignore.