TypeScript

Next.js ofrece una experiencia de desarrollo con TypeScript como prioridad para construir tu aplicación React.

Incluye soporte integrado para TypeScript que instala automáticamente los paquetes necesarios y configura los ajustes adecuados.

Además de un Plugin de TypeScript para tu editor.

🎥 Mira: Aprende sobre el plugin de TypeScript integrado → YouTube (3 minutos)

Nuevos Proyectos

create-next-app ahora incluye TypeScript por defecto.

npx create-next-app@latest

Proyectos Existentes

Agrega TypeScript a tu proyecto renombrando un archivo a .ts / .tsx. Ejecuta next dev y next build para instalar automáticamente las dependencias necesarias y agregar un archivo tsconfig.json con las opciones de configuración recomendadas.

Si ya tenías un archivo jsconfig.json, copia la opción paths del compilador del antiguo jsconfig.json al nuevo archivo tsconfig.json, y elimina el antiguo archivo jsconfig.json.

Plugin de TypeScript

Next.js incluye un plugin personalizado de TypeScript y un verificador de tipos, que VSCode y otros editores de código pueden usar para verificación avanzada de tipos y autocompletado.

Puedes habilitar el plugin en VS Code mediante:

1. Abrir la paleta de comandos (Ctrl/⌘ + Shift + P)
2. Buscar "TypeScript: Select TypeScript Version"
3. Seleccionar "Use Workspace Version"

Ahora, al editar archivos, el plugin personalizado estará habilitado. Al ejecutar next build, se usará el verificador de tipos personalizado.

Características del Plugin

El plugin de TypeScript puede ayudar con:

• Advertencia si se pasan valores inválidos para opciones de configuración de segmentos.
• Mostrar opciones disponibles y documentación en contexto.
• Asegurar que la directiva use client se use correctamente.
• Asegurar que los hooks del cliente (como useState) solo se usen en Componentes del Cliente.

Bueno saber: Se agregarán más características en el futuro.

Versión Mínima de TypeScript

Se recomienda encarecidamente usar al menos la versión v4.5.2 de TypeScript para obtener características de sintaxis como modificadores de tipo en nombres de importación y mejoras de rendimiento.

Enlaces Tipados Estáticamente

Next.js puede tipar estáticamente los enlaces para prevenir errores tipográficos y otros problemas al usar next/link, mejorando la seguridad de tipos al navegar entre páginas.

Para activar esta característica, experimental.typedRoutes debe estar habilitado y el proyecto debe usar TypeScript.

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = nextConfig

Next.js generará una definición de enlace en .next/types que contiene información sobre todas las rutas existentes en tu aplicación, que TypeScript puede usar para proporcionar retroalimentación en tu editor sobre enlaces inválidos.

Actualmente, el soporte experimental incluye cualquier cadena literal, incluyendo segmentos dinámicos. Para cadenas no literales, actualmente necesitas convertir manualmente el href con as Route:

import type { Route } from 'next';
import Link from 'next/link'

// No hay errores de TypeScript si href es una ruta válida
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// Errores de TypeScript si href no es una ruta válida
<Link href="/aboot" />

Para aceptar href en un componente personalizado que envuelve next/link, usa un genérico:

import type { Route } from 'next'
import Link from 'next/link'

function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>Mi Tarjeta</div>
    </Link>
  )
}

¿Cómo funciona?

Al ejecutar next dev o next build, Next.js genera un archivo .d.ts oculto dentro de .next que contiene información sobre todas las rutas existentes en tu aplicación (todas las rutas válidas como el tipo href de Link). Este archivo .d.ts se incluye en tsconfig.json y el compilador de TypeScript verificará ese .d.ts y proporcionará retroalimentación en tu editor sobre enlaces inválidos.

Seguridad de Tipos de Extremo a Extremo

El Enrutador de Aplicaciones de Next.js tiene seguridad de tipos mejorada. Esto incluye:

1. No serialización de datos entre la función de obtención y la página: Puedes hacer fetch directamente en componentes, diseños y páginas en el servidor. Estos datos no necesitan ser serializados (convertidos a una cadena) para pasarse al lado del cliente para su consumo en React. En cambio, dado que app usa Componentes del Servidor por defecto, podemos usar valores como Date, Map, Set, y más sin pasos adicionales. Anteriormente, necesitabas tipar manualmente el límite entre el servidor y el cliente con tipos específicos de Next.js.
2. Flujo de datos optimizado entre componentes: Con la eliminación de _app en favor de diseños raíz, ahora es más fácil visualizar el flujo de datos entre componentes y páginas. Anteriormente, los datos que fluían entre pages individuales y _app eran difíciles de tipar y podían introducir errores confusos. Con obtención de datos colocalizada en el Enrutador de Aplicaciones, esto ya no es un problema.

Obtención de Datos en Next.js ahora proporciona la mayor seguridad de tipos de extremo a extremo posible sin ser prescriptivo sobre tu selección de base de datos o proveedor de contenido.

Podemos tipar los datos de respuesta como esperarías con TypeScript normal. Por ejemplo:

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // El valor de retorno *no* está serializado
  // Puedes retornar Date, Map, Set, etc.
  return res.json()
}

export default async function Page() {
  const name = await getData()

  return '...'
}

Para una seguridad de tipos de extremo a extremo completa, esto también requiere que tu base de datos o proveedor de contenido soporte TypeScript. Esto podría ser mediante un ORM o constructor de consultas con seguridad de tipos.

Error de TypeScript en Componentes del Servidor Asíncronos

Para usar un Componente del Servidor async con TypeScript, asegúrate de usar TypeScript 5.1.3 o superior y @types/react 18.2.8 o superior.

Si estás usando una versión anterior de TypeScript, puedes ver un error de tipo 'Promise<Element>' no es un elemento JSX válido. Actualizar a la última versión de TypeScript y @types/react debería resolver este problema.

Pasando Datos Entre Componentes del Servidor y Cliente

Al pasar datos entre un Componente del Servidor y un Componente del Cliente a través de props, los datos aún se serializan (se convierten a una cadena) para su uso en el navegador. Sin embargo, no necesita un tipo especial. Se tipa igual que pasar cualquier otro prop entre componentes.

Además, hay menos código para serializar, ya que los datos no renderizados no cruzan entre el servidor y el cliente (permanecen en el servidor). Esto solo es posible ahora mediante el soporte para Componentes del Servidor.

Alias de Rutas y baseUrl

Next.js soporta automáticamente las opciones "paths" y "baseUrl" de tsconfig.json.

Puedes aprender más sobre esta característica en la documentación de Alias de Módulos.

Verificación de Tipos en next.config.js

El archivo next.config.js debe ser un archivo JavaScript ya que no es analizado por Babel o TypeScript, pero puedes agregar verificación de tipos en tu IDE usando JSDoc como se muestra a continuación:

// @ts-check

/**
 * @type {import('next').NextConfig}
 **/
const nextConfig = {
  /* opciones de configuración aquí */
}

module.exports = nextConfig

Verificación de Tipos Incremental

Desde v10.2.1 Next.js soporta verificación de tipos incremental cuando está habilitada en tu tsconfig.json, esto puede ayudar a acelerar la verificación de tipos en aplicaciones grandes.

Ignorando Errores de TypeScript

Next.js falla tu compilación de producción (next build) cuando hay errores de TypeScript en tu proyecto.

Si deseas que Next.js produzca código de producción peligrosamente incluso cuando tu aplicación tiene errores, puedes deshabilitar el paso de verificación de tipos integrado.

Si lo deshabilitas, asegúrate de ejecutar verificaciones de tipos como parte de tu proceso de compilación o despliegue, de lo contrario esto puede ser muy peligroso.

Abre next.config.js y habilita la opción ignoreBuildErrors en la configuración de typescript:

module.exports = {
  typescript: {
    // !! ADVERTENCIA !!
    // Permite peligrosamente que las compilaciones de producción se completen con éxito incluso si
    // tu proyecto tiene errores de tipos.
    // !! ADVERTENCIA !!
    ignoreBuildErrors: true,
  },
}

Declaraciones de Tipos Personalizadas

Cuando necesites declarar tipos personalizados, podrías sentirte tentado a modificar next-env.d.ts. Sin embargo, este archivo se genera automáticamente, por lo que cualquier cambio que hagas será sobrescrito. En su lugar, debes crear un nuevo archivo, llamémoslo new-types.d.ts, y referenciarlo en tu tsconfig.json:

{
  "compilerOptions": {
    "skipLibCheck": true
    //...truncado...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

Cambios de Versión