Draft Mode

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 görüntülemek 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 Taslak Modu adlı bir özelliğe sahiptir. İşte nasıl kullanılacağına dair talimatlar.

Step 1: Create and access the API route

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

İlk olarak API rotasını oluşturun. Herhangi bir isme sahip olabilir - örn. pages/api/draft.ts

Bu API rotasında, yanıt nesnesi üzerinde setDraftMode adresini çağırmanız gerekir.

export default function handler(req, res) {
  // ...
  res.setDraftMode({ enable: true })
  // ...
}

Bu, taslak modunu etkinleştirmek için bir çerez ayarlayacaktır. Bu çerezi içeren sonraki istekler, statik olarak oluşturulan sayfaların davranışını değiştirerek Taslak Modunu tetikleyecektir (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/draft.ts

// simple example for testing it manually from your browser.
export default function handler(req, res) {
  res.setDraftMode({ enable: true })
  res.end('Draft mode is enabled')
}

Tarayıcınızın geliştirici araçlarını açar ve /api/draft adresini ziyaret ederseniz, __prerender_bypass adlı bir çerez içeren bir Set-Cookie yanıt başlığı görürsünüz.

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 başsız CMS'nin özel taslak URL'leri ayarlamayı desteklediğini varsaymaktadır. Desteklemiyorsa, taslak URL'lerinizi güvence altına almak için bu yöntemi yine de kullanabilirsiniz, ancak taslak URL'yi 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 taslak URL'lere erişmesini engeller.

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

Terminal

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

<your-site> dağıtım alanınız olmalıdır.
<token> oluşturduğunuz gizli belirteç ile değiştirilmelidir.
<path> görüntülemek istediğiniz sayfanın yolu olmalıdır. Eğer /posts/foo adresini görüntülemek istiyorsanız, &slug=/posts/foo adresini kullanmalısınız.

Başlıksız CMS'niz taslak URL'ye 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, taslak API rotasında:

Gizli bilginin eşleşip eşleşmediğini ve slug parametresinin var olup olmadığını kontrol edin (yoksa istek başarısız olmalıdır).
res.setDraftMode adresini arayın.
Ardından tarayıcıyı slug tarafından belirtilen yola yönlendirin. (Aşağıdaki örnekte 307 yönlendirmesi kullanılmıştır ).

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 draft mode from being enabled
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }
 
  // Enable Draft Mode by setting the cookie
  res.setDraftMode({ enable: true })
 
  // 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ı taslak modu çerezi ile görüntülemek istediğiniz yola yönlendirilecektir.

Step 2: Update `getStaticProps`

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

Çerez ayarlı ( res.setDraftMode aracılığıyla) getStaticProps adresine sahip bir sayfa talep ederseniz, getStaticProps istek anında (derleme zamanı yerine) çağrılacaktır.

Ayrıca, context.draftMode adresinin true olacağı bir context nesnesi ile çağrılacaktır.

export async function getStaticProps(context) {
  if (context.draftMode) {
    // dynamic data
  }
}

Taslak API rotasında res.setDraftMode kullandık, bu nedenle context.draftMode true olacaktır.

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

Fetch draft data

getStaticProps adresini context.draftMode adresine göre farklı veriler 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ştirebilirsiniz:

export async function getStaticProps(context) {
  const url = context.draftMode
    ? 'https://draft.example.com'
    : 'https://production.example.com'
  const res = await fetch(url)
  // ...
}

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

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

Terminal

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

More Details

Varsayılan olarak, Taslak Modu oturumu tarayıcı kapatıldığında sona erer.

Taslak Modu çerezini manuel olarak temizlemek için setDraftMode({ enable: false }) adresini çağıran bir API rotası oluşturun:

pages/api/disable-draft.ts

export default function handler(req, res) {
  res.setDraftMode({ enable: false })
}

Ardından, API Rotasını çağırmak için /api/disable-draft adresine bir istek gönderin. Bu rotayı kullanarak çağırıyorsanız next/linkçerezinin yanlışlıkla silinmesini önlemek için prefetch={false} adresini geçmelisiniz.

Works with `getServerSideProps`

Taslak Modu getServerSideProps ile çalışır ve draftMode adresinde bir tuş olarak bulunur. context nesne.

Bilmekte fayda var: Taslak 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 üzerinde draftMode adresine erişebilecektir. Örneğin:

export default function myApiRoute(req, res) {
  if (req.draftMode) {
    // get draft data
  }
}

Unique per `next build`

next build adresini her çalıştırdığınızda yeni bir bypass çerez değeri oluşturulacaktır.

Bu, bypass çerezinin tahmin edilememesini sağlar.

Bilmekte fayda var: Taslak 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.