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
}
export async function getStaticPaths() {
return {
paths: [
{
params: {
name: 'next.js',
},
}, // Ver la sección "paths" abajo
],
fallback: true, // false o "blocking"
}
}
export async function getStaticProps() {
const res = await fetch('https://api.github.com/repos/vercel/next.js')
const repo = await res.json()
return { props: { repo } }
}
export default function Page({ repo }) {
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 archivosHTML
yJSON
, 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 durantenext build
para cualquierpaths
devuelto durante el buildgetStaticProps
se ejecuta en segundo plano cuando se usafallback: true
getStaticProps
se llama antes del renderizado inicial cuando se usafallback: blocking
¿Dónde puedo usar getStaticPaths?
getStaticPaths
debe usarse congetStaticProps
- No puedes usar
getStaticPaths
congetServerSideProps
- Puedes exportar
getStaticPaths
desde una Ruta Dinámica que también usegetStaticProps
- No puedes exportar
getStaticPaths
desde un archivo que no sea una página (ej. tu carpetacomponents
) - 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.
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 }
}