vercel · kodiakhq · Jul 6, 2023 · Jun 29, 2023 · Jun 29, 2023 · Jun 30, 2023
@@ -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` folder
+
+For new applications, we recommend using the `app` router. This router allows you to use React's latest features, and is currently where we're focusing our development efforts.
+
+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](https://nextjs.org/docs/app/building-your-application/routing/defining-routes).
+
+#### The `pages` folder (optional)
+
+If you prefer to use the older `pages` router instead of `app`, you can create a `pages` folder 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 a custom `_app` file inside your pages folder. 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 custom `_document` file inside your pages folder. 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.