next — npm install next

library1.0.1jsnpmunverified

Next.js is an open-source React framework designed for building performant and scalable web applications. It supports a variety of rendering strategies, including Server-Side Rendering (SSR), Static Site Generation (SSG), Incremental Static Regeneration (ISR), and client-side rendering. The current stable version is 16.2.4. Next.js typically releases new features and major architectural changes, like the App Router and React Server Components, in frequent canary and beta channels, with stable versions receiving backported bug fixes and optimizations. Key differentiators include its file-system-based routing, built-in image and font optimization, API routes for backend functionality, and deep integration with React Server Components for a full-stack development experience. It aims to provide a complete solution for React applications, abstracting much of the build configuration and deployment complexities.

web-framework

npm install next

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEXT

web-frameworkjavascriptv1.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Image

✓ import Image from 'next/image';

✗ import { Image } from 'next/image';

The `Image` component is a default export, not a named export. Ensure proper configuration in `next.config.js` for remote images.

useRouter

✓ import { useRouter } from 'next/navigation'; // App Router import { useRouter } from 'next/router'; // Pages Router

The `useRouter` hook has different import paths for App Router (`next/navigation`) and Pages Router (`next/router`). Using the wrong import or calling it in a Server Component will cause errors.

NextResponse

✓ import { NextResponse } from 'next/server';

✗ import { Response } from 'next/server';

Used in App Router Route Handlers (API routes) to create responses. `NextRequest` is also imported from `next/server` for handling incoming requests.

Link

✓ import Link from 'next/link';

✗ import { Link } from 'next/link';

The `Link` component is a default export for client-side navigation between routes.

Demonstrates a basic Next.js App Router setup with a homepage, an about page with client-side navigation using `Link`, and a simple API Route Handler (`app/api/hello/route.ts`) to fetch dynamic data.

import Link from 'next/link'; import { NextResponse } from 'next/server'; // app/api/hello/route.ts (App Router API Route Handler) export async function GET(request: Request) { const { searchParams } = new URL(request.url); const name = searchParams.get('name') || 'World'; // In a real app, you might fetch data from a database or another API const data = await Promise.resolve({ message: `Hello, ${name}!` }); return NextResponse.json(data); } // app/page.tsx (App Router Page Component) export default function HomePage() { return ( <div> <h1>Welcome to Next.js!</h1> <p>This is a simple homepage.</p> <Link href="/about"> Go to About Page </Link> <p>Try fetching an API route: <a href="/api/hello?name=Registry">/api/hello?name=Registry</a></p> </div> ); } // app/about/page.tsx (App Router Page Component) export default function AboutPage() { return ( <div> <h1>About Us</h1> <p>Learn more about this Next.js application.</p> <Link href="/"> Go to Home </Link> </div> ); } // To set up a new Next.js project, run: // npx create-next-app@latest my-app --typescript --app --eslint // Then, create the files above inside the `my-app` directory.

Debug

Known issues

breakingNext.js 13+ introduced the App Router, a significant architectural shift from the Pages Router. It leverages React Server Components, nested layouts, and new data fetching patterns. Migrating existing Pages Router projects or starting new ones requires understanding these fundamental differences in file conventions, data fetching (no more `getServerSideProps`/`getStaticProps` in App Router components directly), and component lifecycles.

fix

For new projects, use `npx create-next-app@latest --app`. For existing projects, consider a gradual migration using the `next/compat/router` or maintain the Pages Router, understanding that new features will primarily target the App Router.

affects: >=13.0.0

breakingThe `moduleResolution` option in `tsconfig.json` should be updated for modern Node.js and bundler environments. The value `"node"` (which corresponds to `"node10"`) is deprecated for newer Node.js versions which support ESM. `"bundler"` or `"nodenext"` are the recommended values.

fix

Update `compilerOptions.moduleResolution` in your `tsconfig.json` to `"bundler"` (recommended for Next.js) or `"nodenext"`.

affects: >=12.0.0

gotchaEnvironment variables in Next.js have specific rules for client-side access. Only variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. Other environment variables are server-only and accessing them directly in client components will result in `undefined`.

fix

Prefix client-accessible environment variables with `NEXT_PUBLIC_`. For server-only variables, ensure they are only accessed in server-side contexts like API routes, `getServerSideProps` (Pages Router), or Server Components/Route Handlers (App Router).

affects: >=1.0.0

gotchaThe `next/image` component requires careful configuration for remote image optimization. If `images.remotePatterns` is not correctly specified in `next.config.js` for external image sources, images may fail to load, especially in production environments. Additionally, `next/image`'s default loader is not compatible with `next export` for static HTML export unless a custom loader or `unoptimized` prop is used.

fix

For remote images, add entries to `images.remotePatterns` in `next.config.js` matching the hostname of your image provider. For static exports, either use a custom image loader, set `unoptimized={true}` on the `Image` component, or use a standard `<img>` tag.

affects: >=10.0.0

gotchaHydration errors (e.g., "Text content did not match. Server: '...' Client: '...'" or "Expected server HTML to match client HTML") occur when the server-rendered HTML differs from what React expects to render on the client-side during hydration. Common causes include using browser-only APIs (`window`, `localStorage`) during initial render, dynamic content (like dates or random numbers) that differ between server and client, or incorrect HTML nesting.

fix

Move browser-only API calls into `useEffect` hooks, ensure dynamic content is handled client-side or synchronized, and verify correct HTML nesting. The `suppressHydrationWarning={true}` prop can be used as an escape hatch for unavoidable mismatches, but should be used sparingly.

affects: >=1.0.0

Errors

Common errors & fixes

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

A mismatch between server-rendered HTML and client-rendered React component tree, often due to dynamic content or browser-only APIs.

fix

Identify the differing content. Use `useEffect` for client-side only rendering, ensure consistent data across environments, or use `suppressHydrationWarning` on the offending element as a last resort.

Error: Invalid src prop on `next/image`, hostname "example.com" is not configured under images in your `next.config.js`

The `next/image` component is attempting to load an external image from a domain not listed in `images.remotePatterns`.

fix

Add the image hostname (e.g., `example.com`) to the `images.remotePatterns` array in your `next.config.js` file.

TypeError: Cannot read properties of undefined (reading 'useRouter')

The `useRouter` hook is called outside a functional React component, or in a Server Component without the 'use client' directive, or with the wrong import path for the specific router type (App vs. Pages Router).

fix

Ensure `useRouter` is called inside a client component (marked with `'use client'`) and imported from the correct path: `next/navigation` for App Router or `next/router` for Pages Router.

Error: A page without a 'default' export is being exported at 'pages/some-page.js'

A file in the `pages/` directory (or `app/` directory for `page.tsx/jsx`) does not have a default export, which is required for Next.js to recognize it as a page or route.

fix

Add a `export default function MyPage() { ... }` (or an equivalent default export) to the page file.

Error: You're trying to import a component that needs 'fs' but it's not available in the browser.

A component or library intended for server-side Node.js environments (like `fs`, `path`, or `process.env` without `NEXT_PUBLIC_`) is being imported or used in a client-side context.

fix

Refactor the component to avoid server-only dependencies on the client, use dynamic imports with `ssr: false`, or ensure the component is a Server Component and its dependencies are also compatible with the server environment.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

reactrequiredCore UI library for building components.

react-domrequiredProvides DOM-specific rendering methods.

sassoptionalOptional dependency for Sass/SCSS styling support.

@playwright/testoptionalOptional dependency for end-to-end testing with Playwright.

@opentelemetry/apioptionalOptional dependency for OpenTelemetry tracing integration.

babel-plugin-react-compileroptionalOptional, for experimental React Compiler support.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/vercel/next.js ↗

packagehttps://www.npmjs.com/package/next ↗

homepagehttps://nextjs.org ↗