Capítulo 287 de 456

Installation

Core Idea

How to create a new Next.js app with the Pages Router, either via create-next-app or manual setup, including TypeScript, linting, and import aliases.

Key Concepts

  • System requirements: Node.js ≥ 20.9; macOS, Windows (incl. WSL), Linux.
  • Supported browsers: Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+ (zero-config).
  • create-next-app: scaffolds a full project; recommended defaults are TypeScript, ESLint, Tailwind CSS, App Router, AGENTS.md (note: default steers toward App Router even though this page documents Pages Router manual setup).
  • pages directory: file-system routing root for the Pages Router; pages/index.tsx = /.
  • _app.tsx: custom App file defining the global layout wrapper ({ Component, pageProps }).
  • _document.tsx: custom Document file controlling the initial server HTML response (<Html>, <Head />, <Main />, <NextScript />).
  • next typegen: (cross-referenced) generates next-env.d.ts and route types; also produced automatically by next dev/next build.
  • Linting: choice of ESLint or Biome via plain package.json scripts; next lint is gone as of Next.js 16 (next build no longer auto-lints).
  • Absolute imports: via tsconfig.json/jsconfig.json baseUrl + paths.
  • next upgrade: keeps the app current; also refreshes bundled docs at node_modules/next/dist/docs/ so AI coding agents reflect the installed version.

Code Examples

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

import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

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

{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/styles/*": ["styles/*"],
      "@/components/*": ["components/*"]
    }
  }
}
  • O que demonstra: os três arquivos mínimos do Pages Router (index, _app, _document) e a configuração de alias de import.

Reference Tables

ScriptPurpose
next devDev server (Turbopack default)
next buildProduction build
next startProduction server
eslintLint

Anti-patterns

  • Keeping next lint scripts after upgrading to Next.js 16: next build no longer runs the linter automatically; migrate with npx @next/codemod@canary next-lint-to-eslint-cli ..
  • Using webpack's legacy sass ~ import syntax expecting linting to catch stale scripts: unrelated but a reminder that migration codemods exist for exactly these breaking changes.

Key Takeaways

  1. create-next-app's "recommended defaults" push toward App Router; Pages Router requires either the customize-settings flow or manual installation as shown here.
  2. Manual Pages Router setup needs exactly three files to boot: pages/index.tsx, pages/_app.tsx, pages/_document.tsx (the last one optional but common).
  3. TypeScript setup is zero-friction: rename a file to .ts/.tsx and run next dev — Next.js installs deps and writes tsconfig.json automatically.
  4. Minimum TypeScript version is 5.1.0; minimum Node.js is 20.9.
  5. next upgrade is not just a version bump — it refreshes the docs bundled with the package, which downstream AI agents read from disk.

Connects To

  • ch269 next-cli: full CLI reference for next dev/build/start/upgrade/typegen.
  • ch288 project-structure-1: full file/folder convention table for the Pages Router.
AnteriorGetting StartedPróximoProject Structure