getStaticPaths

Si una página tiene Rutas Dinámicas y utiliza getStaticProps, necesita definir una lista de rutas para ser generadas estáticamente.

Cuando exportas una función llamada getStaticPaths (Generación de Sitios Estáticos) desde una página que usa rutas dinámicas, Next.js generará previamente todas las rutas especificadas por getStaticPaths.

import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // Ver la sección "paths" abajo
    ],
    fallback: true, // false o "blocking"
  }
}) satisfies GetStaticPaths

export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}

La referencia de la API getStaticPaths cubre todos los parámetros y props que pueden usarse con getStaticPaths.

¿Cuándo debería usar getStaticPaths?

Deberías usar getStaticPaths si estás generando previamente páginas estáticas que usan rutas dinámicas y:

Los datos provienen de un CMS headless
Los datos provienen de una base de datos
Los datos provienen del sistema de archivos
Los datos pueden almacenarse en caché públicamente (no específicos de usuario)
La página debe generarse previamente (para SEO) y ser muy rápida — getStaticProps genera archivos HTML y JSON, ambos pueden almacenarse en caché por un CDN para mejor rendimiento

¿Cuándo se ejecuta getStaticPaths?

getStaticPaths solo se ejecuta durante el build en producción, no se llama durante el tiempo de ejecución. Puedes validar que el código dentro de getStaticPaths se elimina del bundle del lado del cliente con esta herramienta.

¿Cómo se ejecuta getStaticProps en relación con getStaticPaths?

getStaticProps se ejecuta durante next build para cualquier paths devuelto durante el build
getStaticProps se ejecuta en segundo plano cuando se usa fallback: true
getStaticProps se llama antes del renderizado inicial cuando se usa fallback: blocking

¿Dónde puedo usar getStaticPaths?

getStaticPaths debe usarse con getStaticProps
No puedes usar getStaticPaths con getServerSideProps
Puedes exportar getStaticPaths desde una Ruta Dinámica que también use getStaticProps
No puedes exportar getStaticPaths desde un archivo que no sea una página (ej. tu carpeta components)
Debes exportar getStaticPaths como una función independiente, no como propiedad del componente de página

Se ejecuta en cada petición en desarrollo

En desarrollo (next dev), getStaticPaths se llamará en cada petición.

Generación de rutas bajo demanda

getStaticPaths te permite controlar qué páginas se generan durante el build en lugar de hacerlo bajo demanda con fallback. Generar más páginas durante el build hará que los builds sean más lentos.

Puedes diferir la generación de todas las páginas bajo demanda devolviendo un array vacío para paths. Esto puede ser especialmente útil al desplegar tu aplicación Next.js en múltiples entornos. Por ejemplo, puedes tener builds más rápidos generando todas las páginas bajo demanda para entornos de preview (pero no para builds de producción). Esto es útil para sitios con cientos/miles de páginas estáticas.

pages/posts/[id].js

export async function getStaticPaths() {
  // Cuando esto es true (en entornos de preview) no
  // generes previamente ninguna página estática
  // (builds más rápidos, pero carga inicial más lenta)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // Llama a un API externa para obtener posts
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Obtén las rutas a generar basadas en los posts
  // En entornos de producción, genera previamente todas las páginas
  // (builds más lentos, pero carga inicial más rápida)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } significa que otras rutas deberían devolver 404
  return { paths, fallback: false }
}