System Requirements

First, make sure your development environment meets the following requirements:

  • Node.js 16.8 or later.
  • MacOS, Windows (including WSL), and Linux are supported.

Note: While the pages directory requires Node.js v14 or later, the app directory requires Node v16.8.0 or later.

Automatic Installation

To automatically create a new Next.js project using the app directory:

npx create-next-app@latest --experimental-app
# or
yarn create next-app --experimental-app
# or
pnpm create next-app --experimental-app

create-next-app now ships with TypeScript by default. See TypeScript for more information.

Manual Installation

To create a new Next.js app, install the required packages:

npm install next@latest react@latest react-dom@latest eslint-config-next@latest
# or
yarn add next@latest react@latest react-dom@latest eslint-config-next@latest
# or
pnpm update next@latest react@latest react-dom@latest eslint-config-next@latest

Open package.json and add the following scripts:

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"

These scripts refer to the different stages of developing an application:

  • dev: runs next dev to start Next.js in development mode.
  • build: runs next build to build the application for production usage.
  • start: runs next start to start a Next.js production server.
  • lint: runs next lint to set up Next.js' built-in ESLint configuration.

Next, opt into the beta app directory. Create a next.config.js file in the root directory of your project and add the following code:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,

module.exports = nextConfig;

Create an app folder and add a layout.js, page.js, and head.js files. These will be rendered when the user visits the root of your application.

App Directory with Layout and Page

Add the following code to app/head.js:

export default function Head() {
  return (
      <meta name="viewport" content="width=device-width, initial-scale=1"  />
      <link rel="icon" href="/favicon.ico" />

Add the following code to app/layout.js for your root layout:

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head />

Finally, add the following code to app/page.js:

export default function Page() {
  return <h1>Hello, Next.js!</h1>;

Good to know: If you forget to create a head.js or layout.js, Next.js will automatically create these for you when running the development server.

Running the Development Server

  1. Run npm run dev to start the development server.
  2. Visit http://localhost:3000 to view your application.
  3. Edit app/layout.js or app/page.js and save to see the updated result in your browser.

Next Steps