getStaticProps

Bir sayfadan getStaticProps (Static Site Generation) adlı bir işlevi dışa aktarırsanız, Next.js, getStaticProps tarafından döndürülen propları kullanarak derleme zamanında bu sayfayı önceden oluşturacaktır.

pages/index.tsx

import type { InferGetStaticPropsType, GetStaticProps } from 'next'
 
type Repo = {
  name: string
  stargazers_count: number
}
 
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
}

Oluşturma türüne bakılmaksızın, props adresinin sayfa bileşenine aktarılacağını ve ilk HTML'de istemci tarafında görüntülenebileceğini unutmayın. Bu, sayfanın doğru şekilde hidratlanmasını sağlamak içindir. İstemcide bulunmaması gereken hassas bilgileri props içinde iletmediğinizden emin olun.

When should I use getStaticProps?

Aşağıdaki durumlarda getStaticProps adresini kullanmalısınız:

Sayfayı oluşturmak için gereken veriler, kullanıcının isteğinden önce derleme zamanında mevcuttur
Veriler başsız bir CMS'den geliyor
Sayfa önceden işlenmeli (SEO için) ve çok hızlı olmalıdır - getStaticProps, HTML ve JSON dosyalarını oluşturur, her ikisi de performans için bir CDN tarafından önbelleğe alınabilir
Veriler genel olarak önbelleğe alınabilir (kullanıcıya özel değil). Bu koşul, yolu yeniden yazmak için bir Orta Yazılım kullanılarak belirli özel durumlarda atlanabilir.

When does getStaticProps run

getStaticProps her zaman sunucu üzerinde çalışır ve asla istemci üzerinde çalışmaz. getStaticProps içinde yazılan kodun istemci tarafı paketinden kaldırıldığını bu araçla doğrulayabilirsiniz .

getStaticProps sırasında her zaman çalışır next build
getStaticProps kullanırken arka planda çalışır fallback: true
getStaticProps kullanıldığında ilk render işleminden önce çağrılır fallback: blocking
getStaticProps kullanırken arka planda çalışır revalidate
getStaticProps kullanırken arka planda isteğe bağlı olarak çalışır revalidate()

Artımlı Statik Yenileme ile birleştirildiğinde, getStaticProps eski sayfa yeniden doğrulanırken arka planda çalışacak ve yeni sayfa tarayıcıya sunulacaktır.

getStaticProps statik HTML ürettiği için gelen isteğe (sorgu parametreleri veya HTTP üstbilgileri gibi) erişimi yoktur. Sayfanız için isteğe erişmeniz gerekiyorsa, getStaticProps adresine ek olarak Orta Yazılım kullanmayı düşünün.

Using getStaticProps to fetch data from a CMS

Aşağıdaki örnek, bir CMS'den blog gönderilerinin listesini nasıl getirebileceğinizi göstermektedir.

pages/blog.tsx

// posts will be populated at build time by getStaticProps()
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}
 
// This function gets called at build time on server-side.
// It won't be called on client-side, so you can even do
// direct database queries.
export async function getStaticProps() {
  // Call an external API endpoint to get posts.
  // You can use any data fetching library
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // By returning { props: { posts } }, the Blog component
  // will receive `posts` as a prop at build time
  return {
    props: {
      posts,
    },
  }
}

getStaticProps API referansı, getStaticProps ile kullanılabilecek tüm parametreleri ve sahne donanımlarını kapsar.

Write server-side code directly

getStaticProps yalnızca sunucu tarafında çalıştığından, hiçbir zaman istemci tarafında çalışmayacaktır. Tarayıcı için JS paketine bile dahil edilmeyecektir, böylece tarayıcılara gönderilmeden doğrudan veritabanı sorguları yazabilirsiniz.

Bu, getStaticProps adresinden bir API rotası almak yerine (kendisi harici bir kaynaktan veri alır), sunucu tarafı kodunu doğrudan getStaticProps adresinde yazabileceğiniz anlamına gelir.

Aşağıdaki örneği ele alalım. Bir CMS'den bazı verileri almak için bir API rotası kullanılır. Bu API rotası daha sonra doğrudan getStaticProps adresinden çağrılır. Bu, performansı düşüren ek bir çağrı oluşturur. Bunun yerine, CMS'den veri getirme mantığı bir lib/ dizini kullanılarak paylaşılabilir. Daha sonra getStaticProps ile paylaşılabilir.

lib/load-posts.js

// The following function is shared
// with getStaticProps and API routes
// from a `lib/` directory
export async function loadPosts() {
  // Call an external API endpoint to get posts
  const res = await fetch('https://.../posts/')
  const data = await res.json()
 
  return data
}

pages/blog.js

// pages/blog.js
import { loadPosts } from '../lib/load-posts'
 
// This function runs only on the server side
export async function getStaticProps() {
  // Instead of fetching your `/api` route you can call the same
  // function directly in `getStaticProps`
  const posts = await loadPosts()
 
  // Props returned will be passed to the page component
  return { props: { posts } }
}

Alternatif olarak, veri almak için API rotaları kullanmıyorsanız fetch() API, veri almak için doğrudan getStaticProps adresinde kullanılabilir.

Next.js'nin istemci tarafı paketinden neleri elediğini doğrulamak için next-code-elimination aracını kullanabilirsiniz.

Statically generates both HTML and JSON

getStaticProps içeren bir sayfa derleme sırasında önceden oluşturulduğunda, Next.js, sayfa HTML dosyasına ek olarak getStaticProps çalıştırma sonucunu tutan bir JSON dosyası oluşturur.

Bu JSON dosyası, istemci tarafı yönlendirmede next/link veya next/router. getStaticProps adresini kullanarak önceden oluşturulmuş bir sayfaya gittiğinizde, Next.js bu JSON dosyasını alır (derleme zamanında önceden hesaplanmıştır) ve sayfa bileşeni için prop olarak kullanır. Bu, yalnızca dışa aktarılan JSON kullanıldığından istemci tarafı sayfa geçişlerinin getStaticProps adresini çağırmayacağı anlamına gelir.

Incremental Static Generation kullanıldığında, istemci tarafında gezinme için gereken JSON'u oluşturmak üzere getStaticProps arka planda yürütülecektir. Bunu aynı sayfa için birden fazla istek yapılması şeklinde görebilirsiniz, ancak bu amaçlanmıştır ve son kullanıcı performansı üzerinde hiçbir etkisi yoktur.

Where can I use getStaticProps

getStaticProps yalnızca bir sayfadan dışa aktarılabilir. Sayfa olmayan dosyalardan, _app, _document veya _error adreslerinden dışa aktaramazsınız.

Bu kısıtlamanın nedenlerinden biri, React'in sayfa render edilmeden önce gerekli tüm verilere sahip olması gerektiğidir.

Ayrıca, getStaticProps adresini bağımsız bir işlev olarak kullanmanız gerekir - getStaticProps adresini sayfa bileşeninin bir özelliği olarak eklerseniz çalışmaz.

Bilmenizde fayda var: özel bir uygulama oluşturduysanız, pageProps adresini bağlantılı belgede gösterildiği gibi sayfa bileşenine aktardığınızdan emin olun, aksi takdirde sahne boş olacaktır.

Runs on every request in development

Geliştirme aşamasında (next dev), getStaticProps her istek üzerine çağrılacaktır.

Preview Mode

Önizleme Modunu kullanarak statik oluşturmayı geçici olarak atlayabilir ve sayfayı derleme zamanı yerine istek zamanında oluşturabilirsiniz. Örneğin, başsız bir CMS kullanıyor ve taslakları yayınlanmadan önce önizlemek istiyor olabilirsiniz.