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.

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.

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.

Generación Estática y Renderizado del Lado del Servidor

Para getStaticProps, getStaticPaths, y getServerSideProps, puedes usar los tipos GetStaticProps, GetStaticPaths, y GetServerSideProps respectivamente:

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'

export const getStaticProps = (async (context) => {
  // ...
}) satisfies GetStaticProps

export const getStaticPaths = (async () => {
  // ...
}) satisfies GetStaticPaths

export const getServerSideProps = (async (context) => {
  // ...
}) satisfies GetServerSideProps

Bueno saber: satisfies se agregó a TypeScript en 4.9. Recomendamos actualizar a la última versión de TypeScript.

Rutas API

El siguiente es un ejemplo de cómo usar los tipos integrados para rutas API:

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: 'John Doe' })
}

También puedes tipar los datos de respuesta:

import type { NextApiRequest, NextApiResponse } from 'next'

type Data = {
  name: string
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  res.status(200).json({ name: 'John Doe' })
}

App Personalizado

Si tienes un App personalizado, puedes usar el tipo integrado AppProps y cambiar el nombre del archivo a ./pages/_app.tsx así:

import type { AppProps } from 'next/app'

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

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