Next.js 01 ▲ Installation — create-next-app & project bootstrap - KandZ

⏱️ Estimated read: 12 min | |

Next.js is a React framework that provides the file-system routing, the server-side rendering, and the API layer that the plain React does not include. The installation is a single command that scaffolds the project, installs the dependencies, and configures the tooling. The previous chapters covered the state management and the data fetching in the client-side React; this chapter covers the framework that runs the React on the server as well as the client, and the CLI that creates the project with the sensible defaults.

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The create-next-app command is the official scaffolding tool. It creates the project directory, installs the next, the react, and the react-dom packages, and configures the TypeScript, the ESLint, the Tailwind CSS, and the App Router according to the prompts . The --yes flag skips the prompts and uses the recommended defaults, which is the mechanism for the non-interactive setup in the CI pipelines and the quick start . The alternative is the manual installation, which installs the three packages and adds the scripts to the package.json by hand .

Key point: The create-next-app requires the Node.js 18.18 or later (the recent versions require 20.9), and it creates the project with the App Router by default . The App Router is the file-system routing that maps the app/ directory to the URL paths, with the layout.tsx as the root layout and the page.tsx as the home page . The --yes flag uses the saved preferences or the defaults, which enable the TypeScript, the Tailwind, the App Router, and the Turbopack .

Why the installation requires the create-next-app

The scaffolding problem.

A React project created with the Vite or the Create React App is a client-side application. It has the index.html, the main.tsx, and the App.tsx, but it does not have the server-side rendering, the file-system routing, or the API routes. The create-next-app creates the project with the app/ directory, the layout.tsx, and the page.tsx, and it configures the Next.js compiler and the Turbopack . The scaffolding is the mechanism that starts the project with the framework’s conventions rather than the plain React’s.

The dependency problem.

Next.js depends on the next, the react, and the react-dom packages. The create-next-app installs the three with the compatible versions, and it configures the package.json scripts for the dev, the build, the start, and the lint . The manual installation requires the developer to install the three packages and to add the scripts by hand, which is the mechanism for the projects that already have the package.json and the dependencies .

The configuration problem.

The create-next-app configures the TypeScript (tsconfig.json), the ESLint (eslint.config.mjs), the Tailwind (globals.css and the PostCSS config), and the import alias (@/*) according to the prompts . The manual installation leaves these configurations to the developer, which is the mechanism for the minimal setup and the custom tooling. The choice between the two depends on whether the project needs the standard setup or the custom one.

a. The create-next-app command

The npx create-next-app@latest is the standard invocation, and the --yes flag skips the prompts.

# Interactive: answer the prompts
npx create-next-app@latest

# Non-interactive: use the defaults
npx create-next-app@latest my-app --yes

# Non-interactive with the explicit options
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

The npx create-next-app@latest runs the CLI without the global installation, and the my-app is the project name . The --yes flag uses the recommended defaults: the TypeScript, the ESLint, the Tailwind CSS, the App Router, and the import alias @/* . The explicit flags are the mechanism for the custom setup, and they skip the prompts .

The prompts ask for the project name, the TypeScript, the ESLint, the Tailwind, the src/ directory, the App Router, the Turbopack, and the import alias . The answers determine the files and the dependencies that the CLI creates.

# The prompts (interactive)
What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to use Turbopack? No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes

The Would you like to use App Router? prompt is the most important, because the App Router is the recommended routing model and the Pages Router is the legacy one . The src/ directory is optional, and it separates the application code from the configuration files .

b. The manual installation

The manual installation is the alternative for the projects that already have the package.json and the dependencies.

# Install the packages
npm install next@latest react@latest react-dom@latest

# Add the scripts to the package.json
# {
#   "scripts": {
#     "dev": "next dev",
#     "build": "next build",
#     "start": "next start",
#     "lint": "eslint"
#   }
# }

The npm install next@latest react@latest react-dom@latest installs the three packages . The dev script starts the development server, the build script creates the production build, the start script runs the production server, and the lint script runs the ESLint . The manual installation requires the developer to create the app/ directory, the layout.tsx, and the page.tsx by hand.

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

The layout.tsx is the root layout, and it must contain the <html> and the <body> tags . The page.tsx is the home page, and it is rendered at the / path.

// app/page.tsx (home page)
export default function Page() {
  return <h1>Hello, Next.js!</h1>
}

The page.tsx and the layout.tsx are both rendered when the user visits the root of the application . If the layout.tsx is missing, Next.js creates it automatically when the next dev runs .

c. The project structure and the scripts

The create-next-app creates the project with the standard structure: the app/ directory, the public/ directory, the package.json, the next.config.ts, the tsconfig.json, and the eslint.config.mjs.

my-app/
├── app/
│   ├── layout.tsx      # root layout (required)
│   ├── page.tsx        # home page
│   └── globals.css     # global styles
├── public/             # static assets
├── package.json
├── next.config.ts
├── tsconfig.json
└── eslint.config.mjs

The app/ directory is the file-system routing, and each subdirectory with a page.tsx is a route . The public/ directory contains the static assets, and the files inside it are referenced from the base URL (/) . The next.config.ts is the Next.js configuration, and the tsconfig.json is the TypeScript configuration.

# The scripts in the package.json
npm run dev      # start the development server (Turbopack)
npm run build    # create the production build
npm run start    # start the production server
npm run lint     # run the ESLint

The npm run dev starts the development server on the port 3000, and the npm run build creates the production build . The npm run start runs the production server, and the npm run lint runs the ESLint.

Complete Example Session

# ============================================
# PART 1: CREATE THE PROJECT
# ============================================
npx create-next-app@latest my-app --yes

# ============================================
# PART 2: ENTER THE PROJECT
# ============================================
cd my-app

# ============================================
# PART 3: START THE DEVELOPMENT SERVER
# ============================================
npm run dev

# ============================================
# PART 4: VISIT THE APPLICATION
# ============================================
# Open http://localhost:3000 in the browser

# ============================================
# PART 5: EDIT THE HOME PAGE
# ============================================
# Edit app/page.tsx and save to see the change

# ============================================
# PART 6: CREATE A NEW ROUTE
# ============================================
# Create app/about/page.tsx with the content

# ============================================
# PART 7: VISIT THE NEW ROUTE
# ============================================
# Open http://localhost:3000/about

# ============================================
# PART 8: BUILD FOR PRODUCTION
# ============================================
npm run build

# ============================================
# PART 9: START THE PRODUCTION SERVER
# ============================================
npm run start

# ============================================
# PART 10: RUN THE LINT
# ============================================
npm run lint

The ten parts demonstrate the installation lifecycle: the scaffolding, the project entry, the development server, the browser visit, the home page edit, the new route, the route visit, the production build, the production start, and the lint. The critical step is Part 1: the --yes flag uses the defaults, which enable the TypeScript, the Tailwind, the App Router, and the Turbopack.

Quick Reference

Installation Commands

Command	Purpose
`npx create-next-app@latest`	Interactive scaffolding
`npx create-next-app@latest my-app --yes`	Non-interactive with defaults
`npm install next react react-dom`	Manual installation
`npm run dev`	Start the development server
`npm run build`	Create the production build
`npm run start`	Start the production server

System Requirements

Requirement	Value
Node.js	18.18+ (recent versions 20.9+)
OS	macOS, Windows (WSL), Linux
Browsers	Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+

The Prompts

Prompt	Default
Project name	`my-app`
TypeScript	Yes
ESLint	Yes
Tailwind CSS	Yes
`src/` directory	No
App Router	Yes
Turbopack	Yes
Import alias	`@/*`

The Project Structure

Path	Purpose
`app/layout.tsx`	Root layout (required)
`app/page.tsx`	Home page
`app/about/page.tsx`	The `/about` route
`public/`	Static assets
`next.config.ts`	Next.js configuration

Best Practices

✅ Do This:

# Use the --yes flag for the quick start
npx create-next-app@latest my-app --yes                        # ✅

# Use the App Router for the new projects
# The prompt defaults to Yes                                    # ✅

# Use the TypeScript for the type safety
# The prompt defaults to Yes                                    # ✅

# Run the dev server after the scaffolding
npm run dev                                                    # ✅

# Create the routes as the folders with the page.tsx
mkdir -p app/about && touch app/about/page.tsx                 # ✅

❌ Don’t Do This:

# Use the Pages Router for the new projects
# The App Router is the recommended default                     # ❌

# Skip the Node.js version check
# The old Node.js fails the build                               # ❌

# Forget the layout.tsx
# Next.js auto-creates it, but the explicit is better           # ❌

# Run the production build without the lint
npm run build    # The lint errors fail the build             # ❌

# Use the manual installation without the scripts
# The npm run dev does not exist                                # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The Node.js version error	The old Node.js	Upgrade to 18.18+ or 20.9+
The `app/` directory is missing	The manual installation	Create the `app/layout.tsx` and `app/page.tsx`
The scripts are missing	The manual installation	Add the `dev`, `build`, `start`, `lint`
The port 3000 is in use	Another process	Stop the process or use `-p`
The Turbopack error	The old version	Update the Next.js

Real-World Examples

1. Interactive scaffolding

npx create-next-app@latest

2. Non-interactive with defaults

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

3. Manual installation

npm install next react react-dom

4. Start the dev server

npm run dev

5. Build for production

npm run build

6. Start the production server

npm run start

7. Run the lint

npm run lint

8. Create the root layout

// app/layout.tsx
export default function RootLayout({ children }) {
  return <html><body>{children}</body></html>
}

9. Create the home page

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

10. Create a new route

mkdir -p app/about && touch app/about/page.tsx

Visual

The create-next-app Flow

┌──────────────────────────────────────────────────────────────┐
│  THE CLI SCAFFOLDS THE PROJECT                               │
│                                                              │
│  npx create-next-app@latest my-app --yes                     │
│       │                                                      │
│       ├── creates the my-app/ directory                      │
│       ├── installs next, react, react-dom                    │
│       ├── configures TypeScript, ESLint, Tailwind            │
│       ├── creates app/layout.tsx and app/page.tsx            │
│       └── adds the dev, build, start, lint scripts           │
│                                                              │
│  cd my-app && npm run dev                                    │
│       │                                                      │
│       ▼                                                      │
│  http://localhost:3000                                       │
└──────────────────────────────────────────────────────────────┘

The App Router Structure

┌──────────────────────────────────────────────────────────────┐
│  THE app/ DIRECTORY IS THE FILE-SYSTEM ROUTING               │
│                                                              │
│  app/                                                        │
│  ├── layout.tsx      → the root layout (required)            │
│  ├── page.tsx        → the / route                           │
│  ├── about/                                                  │
│  │   └── page.tsx    → the /about route                      │
│  └── blog/                                                   │
│      └── page.tsx    → the /blog route                       │
│                                                              │
│  Each folder with a page.tsx is a route.                     │
│  The layout.tsx wraps every page in its folder.              │
└──────────────────────────────────────────────────────────────┘

The Scripts

┌──────────────────────────────────────────────────────────────┐
│  THE package.json SCRIPTS                                    │
│                                                              │
│  "dev":   "next dev"        → the development server         │
│  "build": "next build"      → the production build           │
│  "start": "next start"      → the production server          │
│  "lint":  "eslint"          → the ESLint                     │
│                                                              │
│  The Turbopack is the default bundler for the dev.           │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Scaffolding	`npx create-next-app@latest`
Non-interactive	`--yes`
Manual install	`npm install next react react-dom`
Node.js	18.18+ (recent 20.9+)
Default router	App Router
Root layout	`app/layout.tsx`
Home page	`app/page.tsx`
Dev server	`npm run dev`
Production build	`npm run build`
Production start	`npm run start`
Lint	`npm run lint`
Static assets	`public/`

Key takeaways:

The create-next-app is the official scaffolding tool. The npx create-next-app@latest creates the project with the dependencies, the scripts, and the configuration. The --yes flag skips the prompts and uses the recommended defaults: the TypeScript, the ESLint, the Tailwind, the App Router, and the Turbopack .
The App Router is the default and the recommended routing model. The app/ directory maps the folders to the URL paths, with the layout.tsx as the root layout and the page.tsx as the page. Each folder with a page.tsx is a route .
The layout.tsx is required and must contain the <html> and <body> tags. If it is missing, Next.js creates it automatically when the next dev runs, but the explicit file is the better practice .
The manual installation is the alternative. The npm install next react react-dom installs the packages, and the developer adds the scripts and the app/ directory by hand. The manual installation is the mechanism for the projects that already have the dependencies and the custom tooling .
The scripts are the development lifecycle. The npm run dev starts the development server with the Turbopack, the npm run build creates the production build, the npm run start runs the production server, and the npm run lint runs the ESLint .
The Node.js version is the prerequisite. The recent versions require the Node.js 20.9 or later, and the older versions require the 18.18 or later. The old Node.js fails the build before the project starts .

Remember: The Next.js installation is the create-next-app command that scaffolds the project with the dependencies, the scripts, and the configuration. The --yes flag uses the defaults, which enable the TypeScript, the Tailwind, and the App Router. The app/layout.tsx and the app/page.tsx are the root layout and the home page. The npm run dev starts the development server, and the npm run build creates the production build. The result is a project that is ready to develop, with the routing, the styling, and the server-side rendering configured from the first command.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!