Installation

Create a new Next.js app and run it locally.
Before you begin, make sure your development environment meets the following requirements:
Next.js supports modern browsers with zero configuration.
Learn more about browser support, including how to configure polyfills and target specific browsers.
The quickest way to create a new Next.js app is using create-next-app, which sets up everything automatically for you. To create a project, run:
On installation, you'll see the following prompts:
If you choose to customize settings, you'll see the following prompts:
After the prompts, create-next-app will create a folder with your project name and install the required dependencies.
To manually create a new Next.js app, install the required packages:
Then, add the following scripts to your package.json file:
These scripts refer to the different stages of developing an application:
Turbopack is now the default bundler. To use Webpack run next dev --webpack or next build --webpack. See the Turbopack docs for configuration details.
Next.js uses file-system routing, which means the routes in your application are determined by how you structure your files.
Create an app folder. Then, inside app, create a layout.tsx file. This file is the root layout. It's required and must contain the <html> and <body> tags.
Create a home page app/page.tsx with some initial content:
Both layout.tsx and page.tsx will be rendered when the user visits the root of your application (/).
Create a public folder at the root of your project to store static assets such as images, fonts, etc. Files inside public can then be referenced by your code starting from the base URL (/).
You can then reference these assets using the root path (/). For example, public/profile.png can be referenced as /profile.png:
Minimum TypeScript version: v5.1.0
Next.js comes with built-in TypeScript support. To add TypeScript to your project, rename a file to .ts / .tsx and run next dev. Next.js will automatically install the necessary dependencies and add a tsconfig.json file with the recommended config options.
Next.js includes a custom TypeScript plugin and type checker, which VSCode and other code editors can use for advanced type-checking and auto-completion.
You can enable the plugin in VS Code by:
See the TypeScript reference page for more information.
The App Router names files by convention, like page.tsx, layout.tsx, and route.ts, so your editor quickly fills with same-named tabs. Label each tab with its enclosing folders, like blog/[id], so you can tell them apart.
In VS Code 1.88+ or Cursor, add custom editor labels to .vscode/settings.json. Labeling two folders deep keeps dynamic routes like blog/[id]/page.tsx from all collapsing to the same [id] label:
Or copy this prompt to have your coding agent set it up:
JetBrains IDEs (WebStorm, IntelliJ) show the folder for same-named files automatically, so no setup is needed.
Next.js supports linting with either ESLint or Biome. Choose a linter and run it directly via package.json scripts.
If your project previously used next lint, migrate your scripts to the ESLint CLI with the codemod:
If you use ESLint, create an explicit config (recommended eslint.config.mjs). ESLint supports both the legacy .eslintrc.* and the newer eslint.config.mjs formats. See the ESLint API reference for a recommended setup.
Starting with Next.js 16, next build no longer runs the linter automatically. Instead, you can run your linter through NPM scripts.
See the ESLint Plugin page for more information.
Next.js has in-built support for the "paths" and "baseUrl" options of tsconfig.json and jsconfig.json files.
These options allow you to alias project directories to absolute paths, making it easier and cleaner to import modules. For example:
To configure absolute imports, add the baseUrl configuration option to your tsconfig.json or jsconfig.json file. For example:
In addition to configuring the baseUrl path, you can use the "paths" option to "alias" module paths.
For example, the following configuration maps @/components/* to components/*:
Each of the "paths" are relative to the baseUrl location.
Keep your Next.js version up to date. Each release ships security patches, bug fixes, and performance optimizations alongside new features, and staying current keeps every individual upgrade small. Run the upgrade command:
Upgrading also updates the documentation bundled inside the next package at node_modules/next/dist/docs/. New features arrive with their docs, and existing pages pick up new guidance and pitfalls discovered along the way. AI coding agents in your project then work from the version you have installed rather than their training data.