Getting Started
Core Concepts
Troubleshooting
Setting up a new Next.js project is quick and straightforward. You can create a fully configured project automatically using our interactive setup tool, or you can build one manually from scratch. This guide covers both methods, configuration options, and system requirements needed to get your application running smoothly.
Note
Next.js requires Node.js version >=20.9.0. Make sure your system meets this requirement before you begin.
The easiest way to start a new Next.js app is by using the interactive automated tool. It sets up everything from folder structures to styling and linting configurations automatically.
Open your terminal and run the creation command. You can provide your project directory name directly, or run it without arguments to be prompted for a name:
During the setup process, you will be prompted to choose various options for your application, such as language preferences, styling frameworks, bundlers, and directory structures. You can also pass these options directly as flags via the command line.
Supported configuration flags include:
Supported package managers for bootstrapping: npm, pnpm, yarn, bun.
Sources:
packages/create-next-app/index.ts,packages/create-next-app/create-app.ts
Once the tool finishes creating and setting up your files, move into your new project directory and start the development server:
cd my-app
npm run devIf you prefer to set up your Next.js project manually from scratch, follow these steps to initialize your project directory, install dependencies, and configure your scripts.
Create a new folder for your project, navigate into it, and create a basic package file:
mkdir my-app
cd my-app
npm init -yNext.js requires React, React DOM, and the core Next package to function. Install them using your preferred package manager:
npm install next react react-domWarning
Next.js requires both react and react-dom to be explicitly included in the dependencies section of your package.json file. If they are missing, the server will warn you at startup.
Open your package.json file and add the following scripts to allow you to develop, build, and start your application:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}@/* as an import alias shortcut to reference files relative to your root or src/ folder. You can customize this prefix during setup.If you encounter unexpected issues with your environment, dependencies, or package versions, you can run the built-in diagnostic tool to output system information, Node version, package manager versions, and relevant installed libraries:
npx next infoTip
Always check that your installed packages match the latest stable or canary releases if you are reporting a bug or testing new features.