cf3d73a46b
### Why? Whenever I run `create-next-app` and reach this question ``` Would you like to customize the default import alias? No / Yes ``` I always have to select "No", because I don't remember what this default import alias here is. [It _is_ documented to be `@/*`](https://nextjs.org/docs/app/api-reference/create-next-app#non-interactive), but the documentation is relatively hidden and not many people know about it – it's also easy to forget. Even more confusingly, the next question ("What import alias would you like configured?") doesn't have this `@/*` as the default answer, but the user's last choice as the default answer instead (which could be different from `@/*` – making people wonder if Next.js changed their defaults overnight). I suppose it would be better to just make it clear in the prompt itself, so people with skill issues who happen to forget that default value (like me) can still confidently select "Yes" if they want `@/*`, without having to do "No" and manually type `@/*` again. ### How ```diff - Would you like to customize the default import alias? + Would you like to customize the default import alias (@/*)? ```
192 lines
6.6 KiB
Text
192 lines
6.6 KiB
Text
---
|
|
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: Learn about the files and folders in your Next.js project.
|
|
links:
|
|
- getting-started/project-structure
|
|
---
|
|
|
|
System Requirements:
|
|
|
|
- [Node.js 16.14](https://nodejs.org/) or later.
|
|
- macOS, Windows (including WSL), and Linux are supported.
|
|
|
|
## Automatic Installation
|
|
|
|
We recommend starting a new Next.js app using [`create-next-app`](/docs/app/api-reference/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? No / Yes
|
|
Would you like to use ESLint? No / Yes
|
|
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? @/*
|
|
```
|
|
|
|
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:
|
|
|
|
```bash filename="Terminal"
|
|
npm install next@latest react@latest react-dom@latest
|
|
```
|
|
|
|
Open your `package.json` file 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.
|
|
|
|
### Creating directories
|
|
|
|
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](/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.
|
|
|
|
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"
|
|
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 when running the development server with `next dev`.
|
|
|
|
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" switcher
|
|
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)
|
|
|
|
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 `pages/index.tsx`) file and save it to see the updated result in your browser.
|