Next.js

Common errors

• Error: The "next" package requires Node.js version ">=20.9.0".

  cause Your current Node.js version is older than 20.9.0.
  fix Upgrade your Node.js environment to version 20.9.0 or newer. You can use `nvm install 20` and `nvm use 20`, or `volta install node@20`.

• Error: Hydration failed because the initial UI does not match what was rendered on the server.

  cause The HTML rendered by your React components on the server-side differs from what is rendered on the client-side, often due to client-side-only code executing prematurely on the server, or dynamic content changing between renders.
  fix Ensure components render identically on both server and client. Place client-only logic within `useEffect` hooks, use `typeof window` checks, or consider `suppressHydrationWarning` for unavoidable mismatches (with caution).

• Error: "use client" must be at the top of the file.

  cause You are using client-side React features (e.g., `useState`, `useEffect`, event handlers) in an App Router component that is implicitly a Server Component, or the `'use client'` directive is not the very first line of the file.
  fix Add `'use client';` as the absolute first line of the file to mark it as a Client Component, allowing client-side React features. Ensure there are no comments or other statements before it.

• Module not found: Can't resolve 'react'

  cause The `react` or `react-dom` peer dependencies are not correctly installed or are incompatible with the Next.js version, or there are multiple instances of React causing conflicts.
  fix Verify that `react` and `react-dom` versions in your `package.json` match Next.js's peer dependency requirements (`^18.2.0 || ^19.0.0`). Delete your `node_modules` directory and `package-lock.json` (or `yarn.lock`), then run `npm install` (or `yarn install`) again.

Warnings

• breaking Next.js 16.x requires Node.js version 20.9.0 or newer. Running with an older Node.js version will prevent the application from starting.
  Fix: Upgrade your Node.js environment to version 20.9.0 or later. Consider using a Node.js version manager like `nvm` or `volta`.
• breaking Next.js 16.x has strict peer dependencies on React. Ensure your project uses React and React DOM versions `^18.2.0` or `^19.0.0`.
  Fix: Check your `package.json` for `react` and `react-dom` versions. If they don't match `^18.2.0 || ^19.0.0`, update them, delete `node_modules`, and reinstall dependencies (`npm install` or `yarn install`).
• gotcha For Pages Router applications, the Safari `?ts=` cache-buster URL parameter is now specifically scoped to CSS and font assets only. This might change caching behavior for other asset types if you were relying on its broader application.
  Fix: If experiencing caching issues with non-CSS/font assets in Safari within Pages Router, consider implementing alternative cache-busting strategies or adjusting your server's caching headers for those specific asset types.

Install

• npm install next npm
• yarn add next yarn
• pnpm add next pnpm

Imports

• Image
  wrong:

  const Image = require('next/image');

  correct:

  import Image from 'next/image';

  Next.js primarily uses ES Modules, especially within React components. While CommonJS might work in some Node.js contexts, ESM is the recommended approach for client-side and most server-side components.

Quickstart

This code demonstrates a basic Next.js App Router server component. Save this as `app/page.tsx` in a Next.js project to render a simple 'Hello, Next.js!' page.

import React from 'react';

// app/page.tsx
export default function HomePage() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Hello, Next.js!</h1>
      <p>This is a simple server component rendered by Next.js 16.</p>
    </main>
  );
}