TypeScript

Next.js incluye TypeScript integrado, instalando automáticamente los paquetes necesarios y configurando los ajustes adecuados cuando creas un nuevo proyecto con create-next-app.

Para añadir TypeScript a un proyecto existente, renombra un archivo a .ts / .tsx. Ejecuta next dev y next build para instalar automáticamente las dependencias necesarias y añadir un archivo tsconfig.json con las opciones de configuración recomendadas.

Nota importante: Si ya tienes un archivo jsconfig.json, copia la opción del compilador paths del antiguo jsconfig.json al nuevo archivo tsconfig.json, y elimina el antiguo jsconfig.json.

Ejemplos

Verificación de tipos en next.config.ts

Puedes usar TypeScript e importar tipos en tu configuración de Next.js usando next.config.ts.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* opciones de configuración aquí */
}

export default nextConfig

Nota importante: La resolución de módulos en next.config.ts actualmente está limitada a CommonJS. Esto puede causar incompatibilidades con paquetes solo ESM cargados en next.config.ts.

Cuando uses el archivo next.config.js, puedes añadir 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

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 type { 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

Nota importante: satisfies se añadió a TypeScript en la versión 4.9. Recomendamos actualizar a la última versión de TypeScript.

Con Rutas API

El siguiente es un ejemplo de cómo usar los tipos integrados para las 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' })
}

Con App personalizado

Si tienes una App personalizada, 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} />
}

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.

Desactivar errores de TypeScript en producción

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 incluso cuando tu aplicación tenga errores, puedes desactivar el paso de verificación de tipos integrado.

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

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

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  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,
  },
}

export default nextConfig

Nota importante: Puedes ejecutar tsc --noEmit para verificar errores de TypeScript tú mismo antes de compilar. Esto es útil para pipelines de CI/CD donde quieres verificar errores de TypeScript antes de desplegar.

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 se sobrescribirá. En su lugar, deberías crear un nuevo archivo, por ejemplo 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 por versión