Azure Static Web Apps'te karma Next.js web siteleri dağıtma (Önizleme)

Bu öğreticide React Server Components, Server-Side Rendering (SSR) ve API yolları gibi Next.js özellikleri desteğini kullanarak Azure Static Web Apps'e Next.js bir web sitesi dağıtmayı öğreneceksiniz.

Not

Next.js karma destek önizleme aşamasındadır.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
• Bir GitHub hesabı. Ücretsiz hesap oluşturun.
• Node.js uygulamasının yüklenmiş olması.
• Next.js CLI yüklü. Ayrıntılar için Next.js Başlarken kılavuzuna bakın.

Önizlemede desteklenmeyen özellikler

Statik Web Apps'in aşağıdaki özellikleri karma işleme ile Next.js için desteklenmez:

• Azure İşlevleri, Azure Uygulaması Hizmeti, Azure Container Apps veya Azure API Management kullanan bağlı API'ler.
• SWA CLI yerel öykünmesi ve dağıtımı.
• Dosya için staticwebapp.config.json kısmi destek.
  • Gezinti geri dönüşü desteklenmiyor.
  • Next.js uygulamasının içindeki yollara yönlendirme yeniden yazma işlemleri içinde next.config.jsyapılandırılmalıdır.
  • Dosya içindeki yapılandırma, staticwebapp.config.json içindeki next.config.jsyapılandırmadan önceliklidir.
  • Next.js sitesinin yapılandırması, tam özellik uyumluluğu için kullanılarak next.config.js işlenmelidir.
• skip_app_build ve skip_api_build dağıtım görüntüsü içinde Azure/static-web-apps-deploy@v1 kullanılamaz.
• Artımlı statik yeniden oluşturma (ISR), görüntüleri önbelleğe almayı desteklemez.

Not

Karma Next.js uygulaması için maksimum uygulama boyutu 250 MB'tır. İyileştirilmiş uygulama boyutları için Next.js tek başına özelliğini kullanın. Bu yeterli değilse, uygulama boyutu gereksiniminiz 250 MB'tan fazlaysa Statik HTML dışarı aktarılan Next.js kullanmayı göz önünde bulundurun.

Depo oluşturma

Bu makalede, kullanmaya başlamanızı kolaylaştırmak için bir GitHub şablon deposu kullanılmaktadır. Şablonda Azure Static Web Apps'e dağıtılacak bir başlangıç uygulaması bulunur.

1. Yeni bir depo oluşturmak için aşağıdaki konuma gidin.

   https://github.com/staticwebdev/nextjs-hybrid-starter/generate

2. Deponuzu my-first-static-web-app olarak adlandır

3. Şablondan depo oluştur’u seçin.

   

Statik web uygulaması oluşturma

Artık depo oluşturulduğuna göre, Azure portalından statik bir web uygulaması oluşturabilirsiniz.

1. Azure portalına gidin.
2. Kaynak Oluştur’u seçin.
3. Statik Web Uygulamaları'nı arayın.
4. Static Web Apps’ı seçin.
5. Oluştur'u belirleyin.

Temel Bilgiler bölümünde, yeni uygulamanızı yapılandırarak ve bir GitHub deposuna bağlayarak başlayın.

Ayar	Value
Abonelik	Azure aboneliği seçin.
Kaynak Grubu	Yeni oluştur bağlantısını seçin ve metin kutusuna static-web-apps-test yazın.
Veri Akışı Adı	Metin kutusuna my-first-static-web-app girin.
Plan türü	Ücretsiz'i seçin.
Azure İşlevleri ve hazırlama ayrıntıları	Size en yakın bölgeyi seçin.
Source	GitHub'ı seçin.

GitHub ile oturum açın'ı seçin ve GitHub ile kimlik doğrulaması yapın.

GitHub ile oturum açtığınızda depo bilgilerini girin.

Ayar	Value
Kuruluş	Kuruluşunuzu seçin.
Depo	my-first-web-static-app öğesini seçin.
Şube	Ana öğesini seçin.

Not

Herhangi bir depo görmüyorsanız:

• GitHub'da Azure Static Web Apps'i yetkilendirmeniz gerekebilir. GitHub deponuza gidin ve Ayarlar Uygulamalar Yetkili OAuth Uygulamaları'na gidin, Azure Statik Web Uygulamaları'nı ve ardından Ver'i seçin.>>
• Azure DevOps kuruluşunuzda Azure Static Web Apps'i yetkilendirmeniz gerekebilir. İzinleri vermek için kuruluşun sahibi olmanız gerekir. OAuth aracılığıyla üçüncü taraf uygulama erişimi isteyin. Daha fazla bilgi için bkz . OAuth 2.0 ile REST API'lerine erişimi yetkilendirme.

Derleme Ayrıntıları bölümünde, tercih ettiğiniz ön uç çerçevesine özgü yapılandırma ayrıntılarını ekleyin.

1. Derleme Ön Ayarları açılan listesinden Next.js seçin.

2. Uygulama konumu kutusunda varsayılan değeri tutun.

3. Api konum kutusunu boş bırakın.

4. Uygulama yapıt konumu kutusunu boş bırakın.

Gözden geçir ve oluştur’u seçin.

Web sitesini görüntüleme

Statik uygulama dağıtmanın iki yönü vardır. İlki, uygulamanızı oluşturan temel Azure kaynaklarını oluşturur. İkincisi, uygulamanızı derleyen ve yayımlayan bir iş akışıdır.

Yeni statik sitenize gidebilmeniz için önce dağıtım derlemesinin çalıştırılmasını tamamlamanız gerekir.

Statik Web Uygulamalarına Genel Bakış penceresinde, web uygulamanızla etkileşim kurmanıza yardımcı olacak bir dizi bağlantı görüntülenir.

GitHub Actions çalıştırmalarınızın durumunu denetlemek için burayı seçin ifadesinin yer aldığı başlıkta seçim yapmak sizi deponuzda çalışan GitHub Actions'a götürür. Dağıtım işinin tamamlanmasını doğruladıktan sonra, oluşturulan URL aracılığıyla web sitenize gidebilirsiniz.

GitHub Actions iş akışı tamamlandıktan sonra URL bağlantısını seçerek web sitesini yeni sekmede açabilirsiniz.

Değişiklik yapmak için Next.js projenizi yerel olarak ayarlama

1. Yeni depoyu makinenize kopyalayın. YOUR_GITHUB_ACCOUNT_NAME> hesabınızın adıyla değiştirdiğinden <emin olun.

   git clone http://github.com/<YOUR_GITHUB_ACCOUNT_NAME>/my-first-static-web-app
   

2. Projeyi Visual Studio Code'da veya tercih ettiğiniz kod düzenleyicisinde açın.

Sunucu Bileşeni ile Sunucu İşlenmiş verileri ekleme

Uygulama Yönlendiricisi'ni kullanarak Next.js projenize sunucu tarafından işlenen veriler eklemek için, bir Next.js bileşenini düzenleyerek bileşendeki verileri işlemek üzere sunucu tarafı işlemleri ekleyin. Varsayılan olarak, Next.js bileşenleri sunucu tarafından işlenebilen Sunucu Bileşenleri'dir.

1. app/page.tsx Dosyasını açın ve sunucu tarafında hesaplanan bir değişkenin değerini ayarlayan bir işlem ekleyin. Örnek olarak veri getirme veya diğer sunucu işlemleri verilebilir.

   export default function Home() {
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           ...
       );
   }
   

2. next/cache rotanın dinamik olarak işlendiğinden Home emin olmak için öğesini içeri aktarın unstable_noStore ve bileşenin içinde çağırın.

   import { unstable_noStore as noStore } from 'next/cache';
   
   export default function Home() {
       noStore();
   
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           ...
       );
   }
   

   Not

   Bu örnek, sunucunun geçerli saatinin sunucu işlemesini göstermek için bu bileşenin dinamik olarak işlenmesini zorlar. Next.js Uygulama Yönlendiricisi modeli, Next.js uygulamanızın performansını iyileştirmek için tek tek veri isteklerini önbelleğe almayı önerir. Next.js'da veri getirme ve önbelleğe alma hakkında daha fazla bilgi edinin.

3. Home Sunucu tarafı verilerini işlemek için app/pages.tsx dosyasındaki bileşeni güncelleştirin.

   import { unstable_noStore as noStore } from 'next/cache';
   
   export default function Home() {
       noStore();
   
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           <main className="flex min-h-screen flex-col items-center justify-between p-24">
               <div>
                   This is a Next.js application hosted on Azure Static Web Apps with 
                   hybrid rendering. The time on the server is <strong>{timeOnServer}</strong>.
               </div>
           </main>
       );
   }
   

API yolu ekleme

Sunucu Bileşenleri'ne ek olarak, Next.js Next.js uygulamanıza API yolları oluşturmak için kullanabileceğiniz Yol İşleyicileri sağlar. Bu API'ler İstemci Bileşenleri'nde getirilebilir.

Api yolu ekleyerek başlayın.

1. konumunda app/api/currentTime/route.tsxyeni bir dosya oluşturun. Bu dosya, yeni API uç noktası için Yol İşleyicisi'ni barındırıyor.

2. API'den veri döndürmek için bir işleyici işlevi ekleyin.

   import { NextResponse } from 'next/server';
   
   export const dynamic = 'force-dynamic';
   
   export async function GET() { 
       const currentTime = new Date().toLocaleTimeString('en-US');
   
       return NextResponse.json({ 
           message: `Hello from the API! The current time is ${currentTime}.`
       });
   }
   

3. konumunda app/components/CurrentTimeFromAPI.tsxyeni bir dosya oluşturun. Bu bileşen, İstemci Bileşeni için API'yi tarayıcıdan getiren bir kapsayıcı oluşturur.

4. Bu dosyaya API'yi getiren bir istemci bileşeni ekleyin.

   'use client';
   
   import { useEffect, useState } from 'react';
   
   export function CurrentTimeFromAPI(){
       const [apiResponse, setApiResponse] = useState('');
       const [loading, setLoading] = useState(true);
   
       useEffect(() => {
           fetch('/api/currentTime')
               .then((res) => res.json())
               .then((data) => {
               setApiResponse(data.message);
               setLoading(false);
               });
           }, 
       []);
   
       return (
           <div className='pt-4'>
               The message from the API is: <strong>{apiResponse}</strong>
           </div>
       )
   }
   

Bu İstemci Bileşeni, yük tamamlandıktan sonra bileşeni işlemek için React kancası ile useEffect API'yi getirir. yönergesi 'use client' bu öğeyi bir İstemci Bileşeni olarak tanımlar. Daha fazla bilgi için bkz . İstemci Bileşenleri.

1. İstemci Bileşenini içeri aktarmak ve işlemek için app/page.tsx dosyasını CurrentTimeFromAPI düzenleyin.

   import { unstable_noStore as noStore } from 'next/cache';
   import { CurrentTimeFromAPI } from './components/CurrentTimeFromAPI';
   
   export default function Home() {
       noStore();
   
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           <main className="flex min-h-screen flex-col items-center justify-between p-24">
               <div>
                   This is a Next.js application hosted on Azure Static Web Apps with 
                   hybrid rendering. The time on the server is <strong>{timeOnServer}</strong>.
               </div>
               <CurrentTimeFromAPI />
           </main>
       );
   }
   

2. API yolundan elde edilen sonuç sayfada görüntülenir.

Next.js için çalışma zamanı sürümünü yapılandırma

Belirli Next.js sürümleri belirli Node.js sürümleri gerektirir. Belirli bir Node sürümünü yapılandırmak için dosyanızın package.json 'engines' özelliğini bir sürüm belirleyecek şekilde ayarlayabilirsiniz.

{
  ...
  "engines": {
    "node": "18.17.1"
  }
}

Next.js için ortam değişkenlerini ayarlama

Next.js, sunucu tarafı işleme ile hem statik sayfa oluşturmayı hem de dinamik sayfa oluşturmayı desteklemek için derleme zamanında ve istek zamanında ortam değişkenlerini kullanır. Bu nedenle, ortam değişkenlerini hem derleme ve dağıtma görevi içinde hem de Azure Static Web Apps kaynağınızın Ortam değişkenlerinde ayarlayın.

...
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          app_location: "/" 
          api_location: ""
          output_location: "" 
        env:
          DB_HOST: ${{ secrets.DB_HOST }}
          DB_USER: ${{ secrets.DB_USER }}
          DB_DATABASE: ${{ secrets.DB_DATABASE }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
          DB_PORT: ${{ secrets.DB_PORT }}
...

Tek başına özelliği etkinleştirme

Uygulama boyutunuz 250 Mb'ı aştığında, Next.js Çıktı Dosyası İzleme özelliği uygulama boyutunu iyileştirmeye ve performansı iyileştirmeye yardımcı olur.

Çıktı Dosyası İzleme, .next/standalone adlı bir klasörde yerleşik olarak gerekli paket bağımlılıklarıyla uygulamanın tamamının sıkıştırılmış bir sürümünü oluşturur. Bu klasör, ek node_modules bağımlılıkları olmadan kendi başına dağıtılacaktır.

Özelliği etkinleştirmek standalone için aşağıdaki ek özelliği öğesininize next.config.jsekleyin:

module.exports ={
    output:"standalone",
}

Statik dosyaları tek başına çıkışınıza kopyalamak için dosyasındaki package.json komutu da yapılandırmanız build gerekir.

{
  ...
  "scripts": {
    ...
    "build": "next build && cp -r .next/static .next/standalone/.next/ && cp -r public .next/standalone/"
    ...
  }
  ...
}

Azure Static Web Apps'e dağıtım için Next.js yönlendirmenizi ve ara yazılımınızı yapılandırma

Next.js projeniz yönlendirmeler, yeniden yazmalar ve ara yazılım ile yolların özel işlenmesine sahip olacak şekilde yapılandırılabilir. Bu işleyiciler genellikle kimlik doğrulaması, kişiselleştirme, yönlendirme ve uluslararasılaştırma için kullanılır. Özel işleme, Next.js sitenizin varsayılan yönlendirmesini etkiler ve yapılandırmanın Statik Web Apps'te barındırma ile uyumlu olması gerekir.

Statik Web Apps, derleme zamanında sitenize bir sayfa ekleyerek Next.js sitenizin başarıyla dağıtıldığını doğrular. Sayfa olarak adlandırılır public/.swa/health.htmlve Statik Web Apps, adresine gidip /.swa/health.html başarılı bir yanıt doğrulayarak sitenizin başarılı başlangıcını ve dağıtımını doğrular. Yeniden yönlendirmeler ve yeniden yazmalar içeren ara yazılım ve özel yönlendirme, yolun erişimini /.swa/health.html etkileyebilir ve bu da Statik Web Apps'in dağıtım doğrulamasını engelleyebilir. Statik Web Apps'e başarılı bir dağıtım için ara yazılımı ve yönlendirmeyi yapılandırmak için şu adımları izleyin:

1. Ara yazılım yapılandırmanızdaki (veya .js) dosyanızda middleware.ts ile .swa başlayan yolları hariç tutun.

   export const config = {
     matcher: [
       /*
        * Match all request paths except for the ones starting with:
        * - .swa (Azure Static Web Apps)
        */
       '/((?!.swa).*)',
     ],
   }
   

2. ile başlayan yolları dışlamak için içindeki next.config.js yeniden yönlendirmelerinizi yapılandırın .swa

   module.exports = {
       async redirects() {
           return [
             {
               source: '/((?!.swa).*)<YOUR MATCHING RULE>',
               destination: '<YOUR REDIRECT RULE>', 
               permanent: false,
             },
           ]
       },
   };
   

3. ile başlayan yolları dışlamak için içindeki next.config.js yeniden yazma işlemlerinizi yapılandırın .swa

   module.exports = {
       async rewrites() {
           return {
               beforeFiles: [
                   {
                       source: '/((?!.swa).*)<YOUR MATCHING RULE>',
                       destination: '<YOUR REWRITE RULE>', 
                   }
               ]
           }
       },
   };
   

Bu kod parçacıkları, ile başlayan .swa yolların özel yönlendirmeniz veya ara yazılımınız tarafından işlenmesini dışlar. Bu kurallar, dağıtım doğrulaması sırasında yolların beklendiği gibi çözülmesini sağlar.

Next.js için günlüğe kaydetmeyi etkinleştirme

Next.js sunucu API'sinde sorun gidermeye yönelik en iyi yöntemleri izleyerek bu hataları yakalamak için API'ye günlük kaydı ekleyin. Azure'da günlüğe kaydetme, Uygulama Analizler kullanır. Bu SDK'yı önceden yüklemek için özel bir başlatma betiği oluşturmanız gerekir. Daha fazlasını öğrenin:

• Application Analizler + Next.js için örnek ön yükleme betiği
• GitHub sorunu
• Next.js ile önceden yükleme

Kaynakları temizleme

Bu uygulamayı kullanmaya devam etmeyecekseniz, aşağıdaki adımları izleyerek Azure Static Web Apps örneğini silebilirsiniz:

1. Azure portalını açın.
2. Üst arama çubuğundan my-first-web-static-app araması yapın.
3. Uygulama adını seçin.
4. Sil'i seçin.
5. Silme eylemini onaylamak için Evet'i seçin (bu eylemin tamamlanması birkaç dakika sürebilir).

Sonraki adımlar

Uygulama ayarlarını yapılandırma