[Docs] Add manual installation instructions for pages (#51995)

Fixes: #51938
vercel · Jul 6, 2023 · 931b1b5 · 931b1b5
1 parent ec19537
commit 931b1b5
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 10 deletions.
diff --git a/docs/01-getting-started/01-installation.mdx b/docs/01-getting-started/01-installation.mdx
@@ -69,9 +69,15 @@ These scripts refer to the different stages of developing an application:
 - `start`: runs [`next start`](/docs/app/api-reference/next-cli#production) to start a Next.js production server.
 - `lint`: runs [`next lint`](/docs/app/api-reference/next-cli#lint) to set up Next.js' built-in ESLint configuration.
 
-### Create the `app` folder
+### Creating directories
 
-Next, create an `app` folder and add a `layout.tsx` and `page.tsx` file. These will be rendered when the user visits the root of your application.
+Next.js uses file-system routing, which means how you structure your files determines the routes in your application.
+
+#### The `app` directory
+
+For new applications, we recommend using the App Router. This router allows you to use React's latest features and is an evolution of the Pages Router based on community feedback.
+
+To use the `app` router, create an `app/` folder, then add a `layout.tsx` and `page.tsx` file. These will be rendered when the user visits the root of your application (`/`).
 
 <Image
   alt="App Folder Structure"
@@ -123,12 +129,64 @@ export default function Page() {
 
 > **Good to know**: If you forget to create `layout.tsx`, Next.js will automatically create this file for you when running the development server with `next dev`.
 
-### Create the `public` folder
+Learn more about [using the App Router](/docs/app/building-your-application/routing/defining-routes).
+
+#### The `pages` directory (optional)
+
+If you prefer to use the Pages Router instead of the App Router, you can create a `pages/` directory at the root of your project.
+
+Then, add an `index.tsx` file inside your `pages` folder. This will be your home page (`/`):
+
+```tsx filename="pages/index.tsx" switcher
+export default function Page() {
+  return <h1>Hello, Next.js!</h1>
+}
+```
+
+Next, add an `_app.tsx` file inside `pages/` to define the global layout. Learn more about the [custom App file](/docs/pages/building-your-application/routing/custom-app)).
+
+```tsx filename="pages/_app.tsx" switcher
+import type { AppProps } from 'next/app'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />
+}
+```
+
+```jsx filename="pages/_app.js" switcher
+export default function App({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}
+```
+
+Finally, add a `_document.tsx` file inside `pages/` to control the initial response from the server. Learn more about the [custom Document file](/docs/pages/building-your-application/routing/custom-document).
+
+```tsx filename="pages/_document.tsx"
+import { Html, Head, Main, NextScript } from 'next/document'
+
+export default function Document() {
+  return (
+    <Html>
+      <Head />
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  )
+}
+```
+
+Learn more about [using the Pages Router](/docs/pages/building-your-application/routing/pages-and-layouts).
+
+> **Good to know**: Although you can use both routers in the same project, routes in `app` will be prioritized over `pages`. We recommend using only one router in your new project to avoid confusion.
+
+### The `public` folder (optional)
 
 You can optionally create a `public` folder to store static assets such as images, fonts, etc. Files inside `public` directory can then be referenced by your code starting from the base URL (`/`).
 
 ## Run 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.tsx` or `app/page.tsx` and save to see the updated result in your browser.
+3. Edit `app/layout.tsx` (or `pages/index.tsx`) file and save it to see the updated result in your browser.
diff --git a/docs/01-getting-started/02-project-structure.mdx b/docs/01-getting-started/02-project-structure.mdx
@@ -28,12 +28,12 @@ This page provides an overview of the file and folder structure of a Next.js pro
 
 ## Top-level folders
 
-|                                                                         |                                    |
-| ----------------------------------------------------------------------- | ---------------------------------- |
-| [`app`](/docs/app/building-your-application/routing)                    | App Router                         |
-| [`pages`](/docs/pages/building-your-application/routing)                | Pages Router                       |
-| [`public`](/docs/getting-started/installation#create-the-public-folder) | Static assets to be served         |
-| [`src`](/docs/app/building-your-application/configuring/src-directory)  | Optional application source folder |
+|                                                                           |                                    |
+| ------------------------------------------------------------------------- | ---------------------------------- |
+| [`app`](/docs/app/building-your-application/routing)                      | App Router                         |
+| [`pages`](/docs/pages/building-your-application/routing)                  | Pages Router                       |
+| [`public`](/docs/getting-started/installation#the-public-folder-optional) | Static assets to be served         |
+| [`src`](/docs/app/building-your-application/configuring/src-directory)    | Optional application source folder |
 
 ## `app` Routing Conventions