Installation

Create a new Next.js Pages Router project with create-next-app, or add Pages Router to an existing project.

This guide shows you how to create a new Next.js project that uses the Pages Router, or how to set up the Pages Router in an existing project.

Create a new project

Run the following command to scaffold a new Next.js application:

npm

npx create-next-app@latest

yarn

yarn create next-app

pnpm

pnpm create next-app

During setup, you will see the following prompts:

What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to use Turbopack for `next dev`? No / Yes
Would you like to customize the import alias? No / Yes

To use the Pages Router, answer No to “Would you like to use App Router?”. create-next-app will generate a pages/ directory instead of app/.

Start the development server

npm run dev

Open http://localhost:3000 to see your application. Edit pages/index.tsx (or pages/index.js) to start building.

Manual setup

If you prefer to set up Next.js manually:

1. Install dependencies

   npm install next react react-dom
   

   For TypeScript, also install:

   npm install --save-dev typescript @types/react @types/node
   
2. Add scripts to package.json

   package.json

   {
     "scripts": {
       "dev": "next dev",
       "build": "next build",
       "start": "next start"
     }
   }
   
3. Create the pages directory

   Create a pages/ directory at the root of your project. Add an index.tsx file:

   pages/index.tsx

   export default function Home() {
     return <h1>Hello, Pages Router</h1>
   }
   
4. Create a next.config.js (optional)

   next.config.js

   /** @type {import('next').NextConfig} */
   const nextConfig = {}
   
   module.exports = nextConfig
   

TypeScript

Next.js has built-in TypeScript support. Create a tsconfig.json at the root of your project and run next dev—Next.js will automatically configure it for you.

tsconfig.json

{}

Next.js creates a next-env.d.ts file that ensures the Next.js types are picked up by the TypeScript compiler. Do not delete or edit this file.

For the App Router equivalent, see App Router installation.

System requirements

• Node.js 18.18 or later.
• macOS, Windows (including WSL), or Linux.