Preview Mode

Not: Bu özelliğin yerini Taslak Modu almıştır.

Examples

Sayfalar belgesinde ve Veri Getirme belgesinde, getStaticProps ve getStaticPaths adreslerini kullanarak derleme zamanında bir sayfanın nasıl önceden oluşturulacağından(Statik Oluşturma) bahsettik.

Statik Oluşturma, sayfalarınız başsız bir CMS'den veri aldığında kullanışlıdır. Ancak, başsız CMS'nizde bir taslak yazarken ve taslağı hemen sayfanızda önizlemek istediğinizde ideal değildir. Next.js'nin bu sayfaları derleme zamanı yerine istek zamanında oluşturmasını ve yayınlanan içerik yerine taslak içeriği getirmesini istersiniz. Next.js'nin Statik Üretimi yalnızca bu özel durum için atlamasını istersiniz.

Next.js, bu sorunu çözen Önizleme Modu adlı bir özelliğe sahiptir. İşte nasıl kullanılacağına dair talimatlar.

Step 1: Create and access a preview API route

Next.js API Routes'a aşina değilseniz önce API Routes belgelerine göz atın.

İlk olarak, bir önizleme API rotası oluşturun. Herhangi bir isme sahip olabilir - örneğin pages/api/preview.js (veya TypeScript kullanıyorsanız .ts ).

Bu API rotasında, yanıt nesnesi üzerinde setPreviewData adresini çağırmanız gerekir. setPreviewData için argüman bir nesne olmalıdır ve bu getStaticProps tarafından kullanılabilir (bu konuda daha sonra daha fazla bilgi verilecektir). Şimdilik {} adresini kullanacağız.

export default function handler(req, res) {
  // ...
  res.setPreviewData({})
  // ...
}

res.setPreviewData tarayıcıda önizleme modunu açan bazı çerezler ayarlar. Next.js'ye bu çerezleri içeren tüm istekler önizleme modu olarak kabul edilecek ve statik olarak oluşturulan sayfaların davranışı değişecektir (bu konuda daha sonra daha fazla bilgi verilecektir).

Aşağıdaki gibi bir API rotası oluşturarak ve tarayıcınızdan manuel olarak erişerek bunu manuel olarak test edebilirsiniz:

pages/api/preview.js
// simple example for testing it manually from your browser.
export default function handler(req, res) {
  res.setPreviewData({})
  res.end('Preview mode enabled')
}

Tarayıcınızın geliştirici araçlarını açıp /api/preview adresini ziyaret ederseniz, bu istek üzerine __prerender_bypass ve __next_preview_data çerezlerinin ayarlanacağını fark edeceksiniz.

Securely accessing it from your Headless CMS

Pratikte, bu API rotasını başsız CMS'nizden güvenli bir şekilde çağırmak istersiniz. Belirli adımlar hangi başsız CMS'yi kullandığınıza bağlı olarak değişecektir, ancak burada atabileceğiniz bazı genel adımlar vardır.

Bu adımlar, kullandığınız headless CMS'nin özel önizleme URL'leri ayarlamayı desteklediğini varsaymaktadır. Desteklemiyorsa, önizleme URL'lerinizi güvence altına almak için bu yöntemi yine de kullanabilirsiniz, ancak önizleme URL'sini manuel olarak oluşturmanız ve erişmeniz gerekir.

İlk olarak, seçtiğiniz bir token oluşturucuyu kullanarak gizli bir token dizesi oluşturmalısınız. Bu sır yalnızca Next.js uygulamanız ve başsız CMS'niz tarafından bilinecektir. Bu sır, CMS'nize erişimi olmayan kişilerin önizleme URL'lerine erişmesini engeller.

İkinci olarak, başsız CMS'niz özel önizleme URL'leri ayarlamayı destekliyorsa, önizleme URL'si olarak aşağıdakini belirtin. Bu, önizleme API rotanızın pages/api/preview.js adresinde bulunduğunu varsayar.

Terminal
https://<your-site>/api/preview?secret=<token>&slug=<path>

Başlıksız CMS'niz önizleme URL'sine bir değişken eklemenize izin verebilir, böylece <path> CMS'nin verilerine göre dinamik olarak şu şekilde ayarlanabilir: &slug=/posts/{entry.fields.slug}

Son olarak, önizleme API rotasında:

export default async (req, res) => {
  // Check the secret and next parameters
  // This secret should only be known to this API route and the CMS
  if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
    return res.status(401).json({ message: 'Invalid token' })
  }
 
  // Fetch the headless CMS to check if the provided `slug` exists
  // getPostBySlug would implement the required fetching logic to the headless CMS
  const post = await getPostBySlug(req.query.slug)
 
  // If the slug doesn't exist prevent preview mode from being enabled
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }
 
  // Enable Preview Mode by setting the cookies
  res.setPreviewData({})
 
  // Redirect to the path from the fetched post
  // We don't redirect to req.query.slug as that might lead to open redirect vulnerabilities
  res.redirect(post.slug)
}

Başarılı olursa, tarayıcı önizleme modu çerezleri ayarlanmış olarak önizleme yapmak istediğiniz yola yönlendirilecektir.

Step 2: Update getStaticProps

Bir sonraki adım, önizleme modunu desteklemek için getStaticProps adresini güncellemektir.

Önizleme modu çerezleri ayarlanmış olarak getStaticProps adresine sahip bir sayfa talep ederseniz ( res.setPreviewData aracılığıyla), getStaticProps istek anında (derleme zamanı yerine) çağrılacaktır.

Ayrıca, context nesnesi ile çağrılacaktır:

export async function getStaticProps(context) {
  // If you request this page with the preview mode cookies set:
  //
  // - context.preview will be true
  // - context.previewData will be the same as
  //   the argument used for `setPreviewData`.
}

Önizleme API rotasında res.setPreviewData({}) kullandık, bu nedenle context.previewData {} olacaktır. Gerekirse oturum bilgilerini önizleme API rotasından getStaticProps adresine aktarmak için bunu kullanabilirsiniz.

Ayrıca getStaticPaths adresini kullanıyorsanız, context.params adresi de kullanılabilir olacaktır.

Fetch preview data

getStaticProps adresini, context.preview ve/veya context.previewData adreslerine dayalı olarak farklı verileri getirecek şekilde güncelleyebilirsiniz.

Örneğin, headless CMS'niz taslak gönderiler için farklı bir API uç noktasına sahip olabilir. Eğer öyleyse, API uç noktası URL'sini aşağıdaki gibi değiştirmek için context.preview adresini kullanabilirsiniz:

export async function getStaticProps(context) {
  // If context.preview is true, append "/preview" to the API endpoint
  // to request draft data instead of published data. This will vary
  // based on which headless CMS you're using.
  const res = await fetch(`https://.../${context.preview ? 'preview' : ''}`)
  // ...
}

İşte bu kadar! Headless CMS'nizden veya manuel olarak önizleme API rotasına ( secret ve slug ile) erişirseniz, artık önizleme içeriğini görebilmeniz gerekir. Ve taslağınızı yayınlamadan güncellerseniz, taslağı önizleyebilmeniz gerekir.

Bunu headless CMS'nizde önizleme URL'si olarak ayarlayın veya manuel olarak erişin ve önizlemeyi görebilmeniz gerekir.

Terminal
https://<your-site>/api/preview?secret=<token>&slug=<path>

More Details

Bilmekte fayda var: next/router oluşturma sırasında bir isPreview bayrağı gösterir, daha fazla bilgi için yönlendirici nesnesi belgelerine bakın.

Specify the Preview Mode duration

setPreviewData bir options nesnesi olması gereken isteğe bağlı bir ikinci parametre alır. Aşağıdaki anahtarları kabul eder:

setPreviewData(data, {
  maxAge: 60 * 60, // The preview mode cookies expire in 1 hour
  path: '/about', // The preview mode cookies apply to paths with /about
})

Clear the Preview Mode cookies

Varsayılan olarak, Önizleme Modu çerezleri için herhangi bir son kullanma tarihi ayarlanmamıştır, bu nedenle tarayıcı kapatıldığında önizleme oturumu sona erer.

Önizleme Modu çerezlerini manuel olarak temizlemek için clearPreviewData() adresini çağıran bir API rotası oluşturun:

pages/api/clear-preview-mode-cookies.js
export default function handler(req, res) {
  res.clearPreviewData({})
}

Ardından, API Rotasını çağırmak için /api/clear-preview-mode-cookies adresine bir istek gönderin. Bu rotayı kullanarak çağırıyorsanız next/linkbağlantı ön-getirme sırasında clearPreviewData adresinin çağrılmasını önlemek için prefetch={false} adresini geçmelisiniz.

setPreviewData çağrısında bir yol belirtilmişse, aynı yolu clearPreviewData adresine de aktarmanız gerekir:

pages/api/clear-preview-mode-cookies.js
export default function handler(req, res) {
  const { path } = req.query
 
  res.clearPreviewData({ path })
}

previewData size limits

Bir nesneyi setPreviewData adresine aktarabilir ve getStaticProps adresinde kullanılabilir olmasını sağlayabilirsiniz. Ancak, veriler bir çerezde saklanacağı için bir boyut sınırlaması vardır. Şu anda, önizleme verileri 2KB ile sınırlıdır.

Works with getServerSideProps

Önizleme modu getServerSideProps üzerinde de çalışır. Ayrıca preview ve previewData adreslerini içeren context nesnesinde de kullanılabilir.

Bilmekte fayda var: Önizleme Modunu kullanırken Cache-Control başlığını ayarlamamalısınız çünkü atlanamaz. Bunun yerine ISR kullanmanızı öneririz.

Works with API Routes

API Rotaları, istek nesnesi altında preview ve previewData adreslerine erişebilecektir. Örneğin:

export default function myApiRoute(req, res) {
  const isPreview = req.preview
  const previewData = req.previewData
  // ...
}

Unique per next build

next build tamamlandığında hem bypass çerez değeri hem de previewData şifrelemek için kullanılan özel anahtar değişir. Bu, bypass çerezinin tahmin edilememesini sağlar.

Bilmekte fayda var: Önizleme Modunu HTTP üzerinden yerel olarak test etmek için tarayıcınızın üçüncü taraf çerezlerine ve yerel depolama erişimine izin vermesi gerekir.