Skip to content

Commit

Permalink
[Next Docs] Migrate new docs from next-site to Next.js repo (#50701)
Browse files Browse the repository at this point in the history
  • Loading branch information
@delbaoliveira
delbaoliveira committed Jun 8, 2023
1 parent 8c2e5bd commit f4f34e4
Show file tree
Hide file tree
Showing 317 changed files with 22,564 additions and 9,285 deletions.
134 changes: 134 additions & 0 deletions docs/01-getting-started/01-installation.mdx
View file
@@ -0,0 +1,134 @@
---
title: Installation
description: Create a new Next.js application with `create-next-app`. Set up TypeScript, styles, and configure your `next.config.js` file.
related:
title: Next Steps
description: For more information on what to do next, we recommend the following sections
links:
- getting-started/react-essentials
- app/building-your-application
- app/building-your-application/configuring/typescript
---

System Requirements:

- [Node.js 16.8](https://nodejs.org/) or later.
- macOS, Windows (including WSL), and Linux are supported.

## Automatic Installation

We recommend creating a new Next.js app using `create-next-app`, which sets up everything automatically for you. To create a project, run:

```bash filename="Terminal"
npx create-next-app@latest
```

On installation, you'll see the following prompts:

```txt filename="Terminal"
What is your project named? my-app
Would you like to use TypeScript with this project? No / Yes
Would you like to use ESLint with this project? No / Yes
Would you like to use Tailwind CSS with this project? No / Yes
Would you like to use `src/` directory with this project? No / Yes
Use App Router (recommended)? No / Yes
Would you like to customize the default import alias? No / Yes
```

Next.js now ships with TypeScript, ESLint, and Tailwind CSS configuration by default. You can also choose to use the `src` directory for your application code.

After the prompts, `create-next-app` will create a folder with your project name and install the required dependencies.

> **Note:** While you can use the [Pages Router](/docs/pages) in your new project. We recommend starting new applications with the App Router to leverage React's latest features.
## Manual Installation

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

```bash filename="Terminal"
npm install next@latest react@latest react-dom@latest
```

Open `package.json` and add the following `scripts`:

```json filename="package.json"
{
"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`](/docs/app/api-reference/next-cli#development) to start Next.js in development mode.
- `build`: runs [`next build`](/docs/app/api-reference/next-cli#build) to build the application for production usage.
- `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

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.

<Image
alt="App Folder Structure"
srcLight="/docs/light/app-getting-started.png"
srcDark="/docs/dark/app-getting-started.png"
width="1600"
height="363"
/>

Create a [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) inside `app/layout.tsx` with the required `<html>` and `<body>` tags:

```tsx filename="app/layout.tsx" switcher
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
```

```jsx filename="app/layout.js" switcher
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
```

Finally, create a home page `app/page.tsx` with some initial content:

```tsx filename="app/page.tsx" switcher
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
```

```jsx filename="app/page.js" switcher
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
```

> **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

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.
149 changes: 149 additions & 0 deletions docs/01-getting-started/02-project-structure.mdx
View file
@@ -0,0 +1,149 @@
---
title: Next.js Project Structure
nav_title: Project Structure
description: A list of folders and files conventions in a Next.js project
---

This page provides an overview of the file and folder structure of a Next.js project. It covers top-level files and folders, configuration files, and routing conventions within the `app` and `pages` directories.

## Top-level files

| | |
| ------------------------------------------------------------------------------------------- | --------------------------------------- |
| **Next.js** | |
| [`next.config.js`](/docs/app/api-reference/next-config-js) | Configuration file for Next.js |
| [`middleware.ts`](/docs/app/building-your-application/routing/middleware) | Next.js request middleware |
| [`.env`](/docs/app/building-your-application/configuring/environment-variables) | Environment variables |
| [`.env.local`](/docs/app/building-your-application/configuring/environment-variables) | Local environment variables |
| [`.env.production`](/docs/app/building-your-application/configuring/environment-variables) | Production environment variables |
| [`.env.development`](/docs/app/building-your-application/configuring/environment-variables) | Development environment variables |
| `.next-env.d.ts` | TypeScript declaration file for Next.js |
| **Ecosystem** | |
| [`package.json`](/docs/getting-started/installation#manual-installation) | Project dependencies and scripts |
| `.gitignore` | Git files and folders to ignore |
| `tsconfig.json` | Configuration file for TypeScript |
| `jsconfig.json` | Configuration file for JavaScript |
| [`.eslintrc.json`](/docs/app/building-your-application/configuring/eslint) | Configuration file for ESLint |

## 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` Routing Conventions

### Routing Files

| | | |
| ------------------------------------------------------------------------------- | ------------------- | ---------------------------- |
| [`layout`](/docs/app/api-reference/file-conventions/layout) | `.js` `.jsx` `.tsx` | Layout |
| [`page`](/docs/app/api-reference/file-conventions/page) | `.js` `.jsx` `.tsx` | Page |
| [`loading`](/docs/app/api-reference/file-conventions/loading) | `.js` `.jsx` `.tsx` | Loading UI |
| [`not-found`](/docs/app/api-reference/file-conventions/not-found) | `.js` `.jsx` `.tsx` | Not found UI |
| [`error`](/docs/app/api-reference/file-conventions/error) | `.js` `.jsx` `.tsx` | Error UI |
| [`global-error`](/docs/app/api-reference/file-conventions/error#global-errorjs) | `.js` `.jsx` `.tsx` | Global error UI |
| [`route`](/docs/app/api-reference/file-conventions/route) | `.js` `.ts` | API endpoint |
| [`template`](/docs/app/api-reference/file-conventions/template) | `.js` `.jsx` `.tsx` | Re-rendered layout |
| [`default`](/docs/app/api-reference/file-conventions/default) | `.js` `.jsx` `.tsx` | Parallel route fallback page |

### Nested Routes

| | |
| ---------------------------------------------------------------------------- | -------------------- |
| [`folder`](/docs/app/building-your-application/routing#route-segments) | Route segment |
| [`folder/folder`](/docs/app/building-your-application/routing#nested-routes) | Nested route segment |

### Dynamic Routes

| | |
| --------------------------------------------------------------------------------------------------------- | --------------------------- |
| [`[folder]`](/docs/app/building-your-application/routing/dynamic-routes#convention) | Dynamic route segment |
| [`[...folder]`](/docs/app/building-your-application/routing/dynamic-routes) | Catch-all segments |
| [`[[...folder]]`](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | Optional catch-all segments |

### Route Groups and Private Folders

| | |
| ----------------------------------------------------------------------------------- | ------------------------------------------------ |
| [`(folder)`](/docs/app/building-your-application/routing/route-groups#convention) | Group routes without affecting routing |
| [`_folder`](/docs/app/building-your-application/routing/colocation#private-folders) | Opt folder and all child segments out of routing |

### Parallel and Intercepted Routes

| | |
| ---------------------------------------------------------------------------------------------- | -------------------------- |
| [`@folder`](/docs/app/building-your-application/routing/parallel-routes#convention) | Named slot |
| [`(.)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept same level |
| [`(..)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept one level above |
| [`(..)(..)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept two levels above |
| [`(...)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept from root |

### Metadata File Conventions

#### App Icons

| | | |
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------ |
| [`favicon`](/docs/app/api-reference/file-conventions/metadata/app-icons#favicon) | `.ico` | Favicon file |
| [`icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#icon) | `.png` `.svg` | App Icon file |
| [`icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#generate-icons-using-code-js-ts-tsx) | `.ico` `.jpg` `.jpeg` `.png` `.svg` | Generated App Icon |
| [`apple-icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#apple-icon) | `.jpg` `.jpeg`, `.png` | Apple App Icon file |
| [`apple-icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#generate-icons-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Apple App Icon |

#### Open Graph and Twitter Images

| | | |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------- |
| [`opengraph-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#opengraph-image) | `.jpg` `.jpeg` `.png` `.gif` | Open Graph image file |
| [`opengraph-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#generate-images-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Open Graph image |
| [`twitter-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#twitter-image) | `.jpg` `.jpeg` `.png` `.gif` | Twitter image file |
| [`twitter-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#generate-images-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Twitter image |

#### SEO

| | | |
| ------------------------------------------------------------------------------------------- | ----------- | --------------------- |
| [`sitemap`](/docs/app/api-reference/file-conventions/metadata/sitemap#static-sitemapxml) | `.xml` | Sitemap file |
| [`sitemap`](/docs/app/api-reference/file-conventions/metadata/sitemap#generate-a-sitemap) | `.js` `.ts` | Generated Sitemap |
| [`robots`](/docs/app/api-reference/file-conventions/metadata/robots#static-robotstxt) | `.txt` | Robots file |
| [`robots`](/docs/app/api-reference/file-conventions/metadata/robots#generate-a-robots-file) | `.js` `.ts` | Generated Robots file |

## `pages` Routing Conventions

### Special Files

| | | |
| ----------------------------------------------------------------------------------------------------------- | ------------------- | ----------------- |
| [`_app`](/docs/pages/building-your-application/routing/custom-app) | `.js` `.jsx` `.tsx` | Custom App |
| [`_document`](/docs/pages/building-your-application/routing/custom-document) | `.js` `.jsx` `.tsx` | Custom Document |
| [`_error`](/docs/pages/building-your-application/routing/custom-error#more-advanced-error-page-customizing) | `.js` `.jsx` `.tsx` | Custom Error Page |
| [`404`](/docs/pages/building-your-application/routing/custom-error#404-page) | `.js` `.jsx` `.tsx` | 404 Error Page |
| [`500`](/docs/pages/building-your-application/routing/custom-error#500-page) | `.js` `.jsx` `.tsx` | 500 Error Page |

### Routes

| | | |
| ---------------------------------------------------------------------------------------------- | ------------------- | ----------- |
| **Folder convention** | | |
| [`index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Home page |
| [`folder/index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Nested page |
| **File convention** | | |
| [`index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Home page |
| [`file`](/docs/pages/building-your-application/routing/pages-and-layouts) | `.js` `.jsx` `.tsx` | Nested page |

### Dynamic Routes

| | | |
| ----------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------- |
| **Folder convention** | | |
| [`[folder]/index`](/docs/pages/building-your-application/routing/dynamic-routes) | `.js` `.jsx` `.tsx` | Dynamic route segment |
| [`[...folder]/index`](/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) | `.js` `.jsx` `.tsx` | Catch-all segments |
| [`[[...folder]]/index`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all segments |
| **File convention** | | |
| [`[file]`](/docs/pages/building-your-application/routing/dynamic-routes) | `.js` `.jsx` `.tsx` | Dynamic route segment |
| [`[...file]`](/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) | `.js` `.jsx` `.tsx` | Catch-all segments |
| [`[[...file]]`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all segments |

0 comments on commit f4f34e4

Please sign in to comment.