Unverified Commit dc3936b1 authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs: Review Getting Started Section (#53377)

I've started reviewing the docs to identify areas we need to cover / improve. This PR contains minor improvements for the **getting started**, **installation**, and **project structure** pages.


New tasks added to linear: 
- Create [middleware.ts](https://linear.app/vercel/issue/DX-1834/create-middlewarets-api-reference-in-file-conventions) page
- Create [instrumentation.ts](https://linear.app/vercel/issue/DX-1833/create-instrumentationts-api-reference-in-file-conventions) page
parent d393f07e
......@@ -3,11 +3,9 @@ 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
description: Learn about the files and folders in your Next.js project.
links:
- getting-started/react-essentials
- app/building-your-application
- app/building-your-application/configuring/typescript
- getting-started/project-structure
---
System Requirements:
......@@ -17,7 +15,7 @@ System Requirements:
## 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:
We recommend starting 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
......@@ -33,12 +31,16 @@ Would you like to use Tailwind CSS? No / Yes
Would you like to use `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to customize the default import alias? No / Yes
What import alias would you like configured? @/*
```
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.
> **Good to know**:
>
> - Next.js now ships with [TypeScript](/docs/app/building-your-application/configuring/typescript), [ESLint](/docs/app/building-your-application/configuring/eslint), and [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css) configuration by default.
> - You can optionally use a [`src` directory](/docs/app/building-your-application/configuring/src-directory) in the root of your project to separate your application's code from configuration files.
## Manual Installation
To manually create a new Next.js app, install the required packages:
......@@ -47,7 +49,7 @@ To manually create a new Next.js app, install the required packages:
npm install next@latest react@latest react-dom@latest
```
Open `package.json` and add the following `scripts`:
Open your `package.json` file and add the following `scripts`:
```json filename="package.json"
{
......@@ -69,13 +71,13 @@ These scripts refer to the different stages of developing an application:
### Creating directories
Next.js uses file-system routing, which means how you structure your files determines the routes in your application.
Next.js uses file-system routing, which means the routes in your application are determined by how you structure your files.
#### 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.
For new applications, we recommend using the [App Router](/docs/app). This router allows you to use React's latest features and is an evolution of the [Pages Router](/docs/pages) 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 (`/`).
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"
......@@ -125,7 +127,7 @@ 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`.
> **Good to know**: If you forget to create `layout.tsx`, Next.js will automatically create this file when running the development server with `next dev`.
Learn more about [using the App Router](/docs/app/building-your-application/routing/defining-routes).
......@@ -179,9 +181,9 @@ Learn more about [using the Pages Router](/docs/pages/building-your-application/
> **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)
#### 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 (`/`).
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
......
......@@ -6,34 +6,34 @@ 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 folders
| | |
| ------------------------------------------------------------------------ | ---------------------------------- |
| [`app`](/docs/app/building-your-application/routing) | App Router |
| [`pages`](/docs/pages/building-your-application/routing) | Pages Router |
| [`public`](/docs/app/building-your-application/optimizing/static-assets) | Static assets to be served |
| [`src`](/docs/app/building-your-application/configuring/src-directory) | Optional application source folder |
## Top-level files
| | |
| ------------------------------------------------------------------------------------------- | --------------------------------------- |
| **Next.js** | |
| [`next.config.js`](/docs/app/api-reference/next-config-js) | Configuration file for Next.js |
| [`package.json`](/docs/getting-started/installation#manual-installation) | Project dependencies and scripts |
| [`instrumentation.ts`](/docs/app/building-your-application/optimizing/instrumentation) | OpenTelemetry and Instrumentation file |
| [`middleware.ts`](/docs/app/building-your-application/routing/middleware) | Next.js request middleware |
| [`instrumentation.ts`](/docs/app/building-your-application/optimizing/instrumentation) | OpenTelemetry and Instrumentation |
| [`.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 |
| [`.eslintrc.json`](/docs/app/building-your-application/configuring/eslint) | Configuration file for ESLint |
| `.gitignore` | Git files and folders to ignore |
| `.next-env.d.ts` | TypeScript declaration file for Next.js |
| `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#the-public-folder-optional) | Static assets to be served |
| [`src`](/docs/app/building-your-application/configuring/src-directory) | Optional application source folder |
| `postcss.config.js` | Configuration file for Tailwind CSS |
## `app` Routing Conventions
......@@ -60,11 +60,11 @@ This page provides an overview of the file and folder structure of a Next.js pro
### 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) | Catch-all segments |
| [`[[...folder]]`](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | Optional catch-all segments |
| | |
| --------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [`[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) | Catch-all route segment |
| [`[[...folder]]`](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | Optional catch-all route segment |
### Route Groups and Private Folders
......@@ -138,13 +138,13 @@ This page provides an overview of the file and folder structure of a Next.js pro
### 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 |
| | | |
| ----------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------- |
| **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 route segment |
| [`[[...folder]]/index`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all route segment |
| **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 route segment |
| [`[[...file]]`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all route segment |
......@@ -7,13 +7,11 @@ Welcome to the Next.js documentation!
## What is Next.js?
Next.js is a framework for building web applications.
Next.js is a React framework for building full-stack web applications. You use React Components to build user interfaces, and Next.js for additional features and optimizations.
With Next.js, you can build user interfaces using React components. Then, Next.js provides additional structure, features, and optimizations for your application.
Under the hood, Next.js also abstracts and automatically configures tooling needed for React, like bundling, compiling, and more. This allows you to focus on building your application instead of spending time with configuration.
Under the hood, Next.js also abstracts and automatically configures tooling for you, like bundling, compiling, and more. This allows you to focus on building your application instead of spending time setting up tooling.
Whether you're an individual developer or part of a larger team, Next.js can help you build interactive, dynamic, and fast web applications.
Whether you're an individual developer or part of a larger team, Next.js can help you build interactive, dynamic, and fast React applications.
## Main Features
......@@ -23,30 +21,32 @@ Some of the main Next.js features include:
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Routing](/docs/app/building-your-application/routing) | A file-system based router built on top of Server Components that supports layouts, nested routing, loading states, error handling, and more. |
| [Rendering](/docs/app/building-your-application/rendering) | Client-side and Server-side Rendering with Client and Server Components. Further optimized with Static and Dynamic Rendering on the server with Next.js. Streaming on Edge and Node.js runtimes. |
| [Data Fetching](/docs/app/building-your-application/data-fetching) | Simplified data fetching with async/await support in React Components and the `fetch()`s API that aligns with React and the Web Platform. |
| [Data Fetching](/docs/app/building-your-application/data-fetching) | Simplified data fetching with async/await in Server Components, and an extended `fetch` API for request memoization, data caching and revalidation. |
| [Styling](/docs/app/building-your-application/styling) | Support for your preferred styling methods, including CSS Modules, Tailwind CSS, and CSS-in-JS |
| [Optimizations](/docs/app/building-your-application/optimizing) | Image, Fonts, and Script Optimizations to improve your application's Core Web Vitals and User Experience. |
| [TypeScript](/docs/app/building-your-application/configuring/typescript) | Improved support for TypeScript, with better type checking and more efficient compilation, as well as custom TypeScript Plugin and type checker. |
| [API Reference](/docs/app/api-reference) | Updates to the API design throughout Next.js. Please refer to the API Reference Section for new APIs. |
## How to Use These Docs
The sections and pages of the docs are organized sequentially, from basic to advanced, so you can follow them step-by-step when building your Next.js application. However, you can read them in any order or skip to the pages that apply to your use case.
On the left side of the screen, you'll find the docs navbar. The pages of the docs are organized sequentially, from basic to advanced, so you can follow them step-by-step when building your application. However, you can read them in any order or skip to the pages that apply to your use case.
At the top of the sidebar, you'll notice a dropdown menu that allows you to switch between the **App Router** and the **Pages Router** features. Since there are features that are unique to each directory, it's important to keep track of which tab is selected.
On the right side of the screen, you'll see a table of contents that makes it easier to navigate between sections of a page. If you need to quickly find a page, you can use the search bar at the top, or the search shortcut (`Ctrl+K` or `Cmd+K`).
On the right side of the page, you'll see a table of contents that makes it easier to navigate between sections of a page. The breadcrumbs at the top of the page will also indicate whether you're viewing App Router docs or Pages Router docs.
To get started, checkout the [Installation](/docs/getting-started/installation) guide. If you're new to React, we recommend reading the [React Essentials](/docs/getting-started/react-essentials) page.
To get started, checkout the [Installation](/docs/getting-started/installation). If you're new to React or Server Components, we recommend reading the [React Essentials](/docs/getting-started/react-essentials) page.
## App Router vs Pages Router
Next.js has two different routers: the App Router and the Pages Router. The App Router is a newer router that allows you to use React's latest features, such as Server Components and Streaming. The Pages Router is the original Next.js router, which allowed you to build server-rendered React applications and continues to be supported for older Next.js applications.
At the top of the sidebar, you'll notice a dropdown menu that allows you to switch between the **App Router** and the **Pages Router** features. Since there are features that are unique to each directory, it's important to keep track of which tab is selected.
The breadcrumbs at the top of the page will also indicate whether you're viewing App Router docs or Pages Router docs.
## Pre-Requisite Knowledge
Although our docs are designed to be beginner-friendly, we need to establish a baseline so that the docs can stay focused on Next.js functionality. We'll make sure to provide links to relevant documentation whenever we introduce a new concept.
To get the most out of our docs, it's recommended that you have a basic understanding of HTML, CSS, and React. If you need to brush up on your React skills, check out these resources:
- [React: Official React Documentation](https://react.dev/learn)
- [React Essentials](/docs/getting-started/react-essentials)
To get the most out of our docs, it's recommended that you have a basic understanding of HTML, CSS, and React. If you need to brush up on your React skills, check out our [Next.js Foundations Course](/learn/foundations/about-nextjs), which will introduce you to the fundamentals.
## Accessibility
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment