Chapter 1: Environment Setup - Next.js Quick Tutorial

1. Environment Requirements

Next.js 15 requires a recent Node.js runtime. Please verify that your local environment meets the version requirements before installation.

Node.js: 18.17 or above (official minimum requirement); recommended to use 20.x LTS, which has long-term support and good ecosystem compatibility.

Verify the installation in your terminal:

node -v
npm -v

Choose any one of the following package managers:

npm: Bundled with Node, zero configuration.
pnpm: Recommended, uses hard links and content-addressable storage, fast installation with low disk usage.
yarn: A classic choice, compatible with most CI documentation.

💡 Suggestion

For new team projects, consider using pnpm first: fast dependency resolution, and the global store significantly saves disk space. See pnpm official docs for installation.

2. Creating a Next.js Project

Use the official scaffolding tool create-next-app to initialize your project in one step:

npx create-next-app@latest my-app

After running this command, you'll enter an interactive wizard. The recommended options consistent with this tutorial are:

TypeScript: Yes — Type safety, consistent with the Next 15 ecosystem default.
ESLint: Yes — Unified code style.
Tailwind CSS: Yes — Utility-first styling approach, consistent with this tutorial's styles.
src/ directory: Yes — Centralizes application code under src/ for a cleaner structure.
App Router: Yes — Uses the app/ directory (recommended since Next 13+).
Import alias: @/* — Use @/components/foo instead of deep relative paths.

For a non-interactive setup with the same options, use the equivalent command:

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

💡 Key Point

Next.js 15 defaults to App Router (app/) as the primary routing and layout solution, which is the current official recommendation. The legacy Pages Router (pages/) is still available but new projects should use App Router directly.

3. Project Directory Structure

After selecting src/ and App Router, the typical directory looks like this (file names may vary slightly depending on the template):

my-app/
├── src/
│   └── app/
│       ├── layout.tsx      # 根布局
│       ├── page.tsx        # 首页
│       ├── globals.css     # 全局样式
│       └── favicon.ico
├── public/                 # 静态资源
├── next.config.ts          # Next.js 配置
├── tsconfig.json           # TypeScript 配置
├── tailwind.config.ts      # Tailwind 配置
├── package.json
└── .eslintrc.json

layout.tsx: Root layout, wraps the current route segment and its child routes' UI; can be nested. Commonly used for html/body, fonts, and global Providers.
page.tsx: Route page component, the renderable content corresponding to a URL; combined with layout.tsx to form a complete page.
next.config.ts: Configuration entry for Next.js build and runtime behavior (compression, image domains, redirects, etc.).

layout.tsx Example

The root layout exports metadata and wraps children in the root structure:

import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="zh-CN">
      <body className="antialiased">{children}</body>
    </html>
  );
}

page.tsx Example

The homepage default exports a React component, serving as the UI for route /:

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1 className="text-4xl font-bold">Welcome to Next.js</h1>
      <p className="mt-4 text-gray-600">编辑 src/app/page.tsx 开始开发。</p>
    </main>
  );
}

4. Development Commands

After entering the project directory, common scripts are defined in the scripts section of package.json. If using pnpm / yarn, simply replace npm with the corresponding command.

Command	Purpose
npm run dev	Start the dev server, default at `http://localhost:3000`, supports Fast Refresh.
npm run build	Build production-optimized output (to `.next`).
npm run start	Start the production-mode Node server on an already built project (requires `build` first).
npm run lint	Run ESLint to check code standards and common errors.

5. next.config.ts Basic Configuration

Next.js 15 recommends using a TypeScript configuration file. Here's a starter example with common options (trim as needed for your project):

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactStrictMode: true,
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "example.com",
        pathname: "/images/**",
      },
    ],
  },
  // 按需启用实验特性；具体项以官方文档为准
  // experimental: { ... },
};

export default nextConfig;

reactStrictMode: Enables React strict mode in development, helping detect side-effect issues; production build behavior follows React documentation.
images.remotePatterns: When loading external domain images with next/image, you must declare allowed protocols, hosts, and path patterns here (security allowlist).
experimental: Toggles for experimental APIs; check the next.config.js docs before minor version upgrades to avoid relying on unstable features.

6. Recommended VS Code Configuration

Developers with React experience can install the following extensions to improve daily development efficiency:

ES7+ React/Redux/React-Native snippets: Quickly insert function components, hooks, and other snippets.
Tailwind CSS IntelliSense: Class name autocompletion and preview (works with Tailwind templates).
ESLint: Integrates with project ESLint rules, highlights issues on save.
Prettier: Unified formatting; recommended to use with eslint-config-prettier to avoid rule conflicts.

Comparison with Vite + React

Next.js provides out-of-the-box server-side rendering (SSR), static generation (SSG), file-system-based App Router, and same-repository Route Handlers (formerly API route capabilities); while a typical Vite + React scaffold leans more toward SPA, where these capabilities often require manual selection and assembly of plugins and servers. If your goal is full-stack or SEO-friendly sites, Next's default setup saves more effort.

7. Chapter Summary

Environment & Toolchain

Confirm Node 18.17+ (recommend 20 LTS), verify with node -v / npm -v; choose from npm / pnpm / yarn.

Project Creation

Use create-next-app@latest, enable TypeScript, ESLint, Tailwind, src/, App Router, and @/* alias.

Directory & Entry Points

Understand app/layout.tsx (root layout) and app/page.tsx (page); static assets go in public/.

Scripts & Configuration

Master dev / build / start / lint; configure strict mode, image remote domains, etc. in next.config.ts as needed.