Crear una nueva aplicación Next.js

Requisitos del sistema

Antes de comenzar, asegúrate de que tu sistema cumpla con los siguientes requisitos:

Node.js 18.18 o superior.
macOS, Windows (incluyendo WSL) o Linux.

Instalación automática

La forma más rápida de crear una nueva aplicación Next.js es usando create-next-app, que configura todo automáticamente. Para crear un proyecto, ejecuta:

Terminal

npx create-next-app@latest

Durante la instalación, verás los siguientes prompts:

Terminal

¿Cómo quieres llamar a tu proyecto? mi-app
¿Deseas usar TypeScript? No / Sí
¿Deseas usar ESLint? No / Sí
¿Deseas usar Tailwind CSS? No / Sí
¿Prefieres tu código dentro de un directorio `src/`? No / Sí
¿Deseas usar el Enrutador de Aplicación? (recomendado) No / Sí
¿Deseas usar Turbopack para `next dev`? No / Sí
¿Quieres personalizar el alias de importación (`@/*` por defecto)? No / Sí
¿Qué alias de importación deseas configurar? @/*

Después de los prompts, create-next-app creará una carpeta con el nombre de tu proyecto e instalará las dependencias necesarias.

Instalación manual

Para crear manualmente una nueva aplicación Next.js, instala los paquetes requeridos:

Terminal

npm install next@latest react@latest react-dom@latest

Luego, agrega los siguientes scripts a tu archivo package.json:

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

Estos scripts corresponden a las diferentes etapas de desarrollo de una aplicación:

next dev: Inicia el servidor de desarrollo.
next build: Construye la aplicación para producción.
next start: Inicia el servidor de producción.
next lint: Ejecuta ESLint.

Crear el directorio `pages`

Next.js usa enrutamiento basado en el sistema de archivos, lo que significa que las rutas en tu aplicación se determinan por cómo estructuras tus archivos.

Crea un directorio pages en la raíz de tu proyecto. Luego, agrega un archivo index.tsx dentro de tu carpeta pages. Esta será tu página de inicio (/):

export default function Page() {
  return <h1>¡Hola, Next.js!</h1>
}

A continuación, agrega un archivo _app.tsx dentro de pages/ para definir el layout global. Más información sobre el archivo App personalizado.

import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

Finalmente, agrega un archivo _document.tsx dentro de pages/ para controlar la respuesta inicial del servidor. Más información sobre el archivo Document personalizado.

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

Crear la carpeta `public` (opcional)

Crea una carpeta public en la raíz de tu proyecto para almacenar recursos estáticos como imágenes, fuentes, etc. Los archivos dentro de public pueden ser referenciados por tu código usando la URL base (/).

Puedes referenciar estos recursos usando la ruta raíz (/). Por ejemplo, public/profile.png puede referenciarse como /profile.png:

import Image from 'next/image'

export default function Page() {
  return <Image src="/profile.png" alt="Perfil" width={100} height={100} />
}

Ejecutar el servidor de desarrollo

Ejecuta npm run dev para iniciar el servidor de desarrollo.
Visita http://localhost:3000 para ver tu aplicación.
Edita el archivo pages/index.tsx y guárdalo para ver los cambios actualizados en tu navegador.

Configurar TypeScript

Versión mínima de TypeScript: v4.5.2

Next.js incluye soporte integrado para TypeScript. Para agregar TypeScript a tu proyecto, renombra un archivo a .ts / .tsx y ejecuta next dev. Next.js instalará automáticamente las dependencias necesarias y agregará un archivo tsconfig.json con las opciones de configuración recomendadas.

Consulta la página de referencia de TypeScript para más información.

Configurar ESLint

Next.js incluye ESLint integrado. Instala automáticamente los paquetes necesarios y configura los ajustes adecuados cuando creas un nuevo proyecto con create-next-app.

Para agregar ESLint manualmente a un proyecto existente, agrega next lint como script en package.json:

package.json

{
  "scripts": {
    "lint": "next lint"
  }
}

Luego, ejecuta npm run lint y serás guiado a través del proceso de instalación y configuración.

Terminal

npm run lint

Verás un prompt como este:

? ¿Cómo deseas configurar ESLint?

❯ Estricto (recomendado)
Base
Cancelar

Estricto: Incluye la configuración base de ESLint de Next.js junto con un conjunto de reglas más estrictas para Core Web Vitals. Esta es la configuración recomendada para desarrolladores que configuran ESLint por primera vez.
Base: Incluye solo la configuración base de ESLint de Next.js.
Cancelar: Omite la configuración. Selecciona esta opción si planeas configurar tu propia configuración personalizada de ESLint.

Si seleccionas Estricto o Base, Next.js instalará automáticamente eslint y eslint-config-next como dependencias en tu aplicación y creará un archivo .eslintrc.json en la raíz de tu proyecto que incluirá tu configuración seleccionada.

Ahora puedes ejecutar next lint cada vez que quieras ejecutar ESLint para detectar errores. Una vez configurado ESLint, también se ejecutará automáticamente durante cada construcción (next build). Los errores harán fallar la construcción, mientras que las advertencias no.

Consulta la página del Plugin ESLint para más información.

Configurar importaciones absolutas y alias de rutas de módulos

Next.js tiene soporte integrado para las opciones "paths" y "baseUrl" de los archivos tsconfig.json y jsconfig.json.

Estas opciones te permiten asignar alias a directorios del proyecto como rutas absolutas, haciendo más fácil y limpio importar módulos. Por ejemplo:

// Antes
import { Button } from '../../../components/button'

// Después
import { Button } from '@/components/button'

Para configurar importaciones absolutas, agrega la opción baseUrl a tu archivo tsconfig.json o jsconfig.json. Por ejemplo:

tsconfig.json o jsconfig.json

{
  "compilerOptions": {
    "baseUrl": "src/"
  }
}

Además de configurar la ruta baseUrl, puedes usar la opción "paths" para asignar alias a rutas de módulos.

Por ejemplo, la siguiente configuración mapea @/components/* a components/*:

tsconfig.json o jsconfig.json

{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/styles/*": ["styles/*"],
      "@/components/*": ["components/*"]
    }
  }
}

Cada una de las rutas "paths" es relativa a la ubicación baseUrl.

Crear una nueva aplicación Next.js

On this page