Hybride Next.js-websites implementeren in Azure Static Web Apps (preview)

In deze zelfstudie leert u hoe u een Next.js-website implementeert in Azure Static Web Apps, met behulp van de ondersteuning voor Next.js functies zoals React Server Components, Server Side Rendering (SSR) en API-routes.

Notitie

Next.js hybride ondersteuning beschikbaar is in preview.

Vereisten

• Een Azure-account met een actief abonnement. Gratis een account maken
• Een GitHub-account. Gratis een account maken
• Node.js geïnstalleerd.
• Next.js CLI geïnstalleerd. Raadpleeg de handleiding Next.js Aan de slag voor meer informatie.

Niet-ondersteunde functies in preview

De volgende functies van Static Web Apps worden niet ondersteund voor Next.js met hybride rendering:

• Gekoppelde API's met behulp van Azure Functions, Azure-app Service, Azure Container Apps of Azure API Management.
• SWA CLI lokale emulatie en implementatie.
• Gedeeltelijke ondersteuning voor staticwebapp.config.json bestand.
  • Terugval van navigatie wordt niet ondersteund.
  • Route herschrijft naar routes binnen de Next.js toepassing moet worden geconfigureerd binnen next.config.js.
  • De configuratie in het staticwebapp.config.json bestand heeft voorrang op de configuratie binnen next.config.js.
  • De configuratie voor de Next.js-site moet worden verwerkt voor next.config.js volledige functiecompatibiliteit.
• skip_app_build en skip_api_build kan niet worden gebruikt binnen de installatiekopieën van de Azure/static-web-apps-deploy@v1 implementatie.
• Incrementele statische regeneratie (ISR) biedt geen ondersteuning voor caching-installatiekopieën.

Notitie

De maximale app-grootte voor de hybride Next.js-toepassing is 250 MB. Gebruik de zelfstandige functie door Next.js voor geoptimaliseerde app-grootten. Als dit niet voldoende is, kunt u overwegen statische HTML-geëxporteerde Next.js te gebruiken als uw app-grootte meer dan 250 MB vereist is.

Een opslagplaats maken

In dit artikel wordt gebruikgemaakt van een GitHub-opslagplaatssjabloon, zodat u eenvoudig aan de slag kunt gaan. De sjabloon bevat een starter-app die moet worden geïmplementeerd in Azure Static Web Apps.

1. Navigeer naar de volgende locatie om een nieuwe opslagplaats te maken.

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

2. Geef de opslagplaats de naam mijn-eerste-statische-web-app

3. Selecteer Opslagplaats maken van sjabloon.

   

Statische web-app maken

Nu de opslagplaats is gemaakt, kunt u een statische web-app maken in de Azure-portal.

1. Ga naar de Azure-portal.
2. Selecteer Een resource maken.
3. Zoek Static Web Apps.
4. Selecteer Statische web-apps.
5. Selecteer Maken.

Op het tabblad Basisbeginselen kunt u de nieuwe app configureren en aan een GitHub-opslagplaats koppelen.

Instelling	Weergegeven als
Abonnement	Selecteer uw Azure-abonnement.
Resourcegroep	Selecteer de koppeling Nieuwe maken en voer static-web-apps-test in het tekstvak in.
Naam	Voer my-first-static-web-app in het tekstvak in.
Abonnementtype	Selecteer Gratis.
Details van Azure Functions en fasering	Selecteer een regio die het dichtst bij u in de buurt ligt.
Bron	Selecteer GitHub.

Selecteer Aanmelden met GitHub en verifieer met GitHub.

Nadat u zich hebt aangemeld bij GitHub, voert u de gegevens van de opslagplaats in.

Instelling	Weergegeven als
Organisatie	Selecteer uw organisatie.
Opslagplaats	Selecteer mijn-eerste-statische-web-app.
Vertakking	Selecteer de hoofdmap.

Notitie

Als u geen opslagplaatsen ziet:

• Mogelijk moet u Azure Static Web Apps autoriseren in GitHub. Blader naar uw GitHub-opslagplaats en ga naar Instellingen Toepassingen geautoriseerde OAuth-apps, selecteer Azure Static Web Apps en selecteer Vervolgens Verlenen.>>
• Mogelijk moet u Azure Static Web Apps autoriseren in uw Azure DevOps-organisatie. U moet een eigenaar van de organisatie zijn om de machtigingen te verlenen. Vraag toegang tot toepassingen van derden aan via OAuth. Zie Toegang tot REST API's autoriseren met OAuth 2.0 voor meer informatie.

Voeg in de sectie Build-details configuratiegegevens toe die specifiek zijn voor het front-end-framework van uw keuze.

1. Selecteer Next.js in de vervolgkeuzelijst Build Presets.

2. Behoud de standaardwaarde in het vak App-locatie .

3. Laat het vak Api-locatie leeg.

4. Laat het locatievak van het app-artefact leeg.

Selecteer Controleren + maken.

De website weergeven

Het implementeren van een statische app heeft twee aspecten. De eerste maakt de onderliggende Azure-resources waaruit uw app bestaat. De tweede is een werkstroom waarmee uw toepassing wordt gebouwd en gepubliceerd.

Voordat u naar uw nieuwe statische site kunt gaan, moet de implementatie-build eerst worden uitgevoerd.

In het overzichtsvenster van Static Web Apps wordt een reeks koppelingen weergegeven waarmee u kunt communiceren met uw web-app.

Als u op de banner selecteert, selecteert u hier om de status van uw GitHub Actions-uitvoeringen te controleren, gaat u naar de GitHub Actions die worden uitgevoerd op uw opslagplaats. Zodra u hebt gecontroleerd of de implementatietaak is voltooid, kunt u via de gegenereerde URL naar uw website gaan.

Zodra de werkstroom voor GitHub Actions is voltooid, kunt u op de URL-koppeling klikken om de website te openen in een nieuw tabblad.

Uw Next.js-project lokaal instellen om wijzigingen aan te brengen

1. Kloon de nieuwe opslagplaats naar uw computer. Zorg ervoor dat u YOUR_GITHUB_ACCOUNT_NAME> vervangt door <uw accountnaam.

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

2. Open het project in Visual Studio Code of de gewenste code-editor.

Servergeenderde gegevens toevoegen met een serveronderdeel

Als u servergeenderde gegevens wilt toevoegen aan uw Next.js-project met behulp van de App Router, bewerkt u een Next.js-onderdeel om bewerkingen aan de serverzijde toe te voegen om gegevens in het onderdeel weer te geven. Standaard zijn Next.js onderdelen Serveronderdelen die door de server kunnen worden gerenderd.

1. Open het app/page.tsx bestand en voeg een bewerking toe waarmee de waarde van een variabele wordt ingesteld, die aan de serverzijde wordt berekend. Voorbeelden hiervan zijn het ophalen van gegevens of andere serverbewerkingen.

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

2. Importeer unstable_noStore en next/cache roep deze aan in het Home onderdeel om ervoor te zorgen dat de route dynamisch wordt weergegeven.

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

   Notitie

   In dit voorbeeld wordt dynamische rendering van dit onderdeel gedwongen om serverweergave van de huidige tijd van de server te demonstreren. Het App Router-model van Next.js raadt aan om afzonderlijke gegevensaanvragen in de cache op te slaan om de prestaties van uw Next.js-app te optimaliseren. Lees meer over het ophalen en opslaan in cache van gegevens in Next.js.

3. Werk het Home onderdeel in app/pages.tsx bij om de gegevens aan de serverzijde weer te geven.

   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>
       );
   }
   

Een API-route toevoegen

Naast Server components biedt Next.js routehandlers die u kunt gebruiken om API-routes naar uw Next.js toepassing te maken. Deze API's kunnen worden opgehaald in clientonderdelen.

Begin met het toevoegen van een API-route.

1. Maak een nieuw bestand op app/api/currentTime/route.tsx. Dit bestand bevat de route-handler voor het nieuwe API-eindpunt.

2. Voeg een handlerfunctie toe om gegevens van de API te retourneren.

   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. Maak een nieuw bestand op app/components/CurrentTimeFromAPI.tsx. Met dit onderdeel maakt u een container voor het clientonderdeel waarmee de API uit de browser wordt opgehaald.

4. Voeg een clientonderdeel toe waarmee de API in dit bestand wordt opgehaald.

   '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>
       )
   }
   

Met dit clientonderdeel wordt de API opgehaald met een useEffect React-hook om het onderdeel weer te geven nadat de belasting is voltooid. De 'use client' richtlijn identificeert dit element als een clientonderdeel. Zie Clientonderdelen voor meer informatie.

1. Bewerk app/page.tsx om het CurrentTimeFromAPI clientonderdeel te importeren en weer te geven.

   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. Het resultaat van de API-route wordt weergegeven op de pagina.

De runtimeversie voor Next.js configureren

Voor bepaalde Next.js versies zijn specifieke Node.js versies vereist. Als u een specifieke Node-versie wilt configureren, kunt u de eigenschap Engines van uw package.json bestand instellen om een versie aan te wijzen.

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

Omgevingsvariabelen instellen voor Next.js

Next.js maakt gebruik van omgevingsvariabelen tijdens het bouwen en op aanvraag, ter ondersteuning van zowel het genereren van statische pagina's als het genereren van dynamische pagina's met serverzijde rendering. Stel daarom omgevingsvariabelen in zowel de build- als de implementatietaak in, en in de omgevingsvariabelen van uw Azure Static Web Apps-resource.

...
      - 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 }}
...

Zelfstandige functie inschakelen

Wanneer de grootte van uw toepassing groter is dan 250 Mb, helpt de functie Next.js Voor het traceren van uitvoerbestanden de app-grootte te optimaliseren en de prestaties te verbeteren.

Uitvoerbestandtracering maakt een gecomprimeerde versie van de hele toepassing met de benodigde pakketafhankelijkheden die zijn ingebouwd in een map met de naam .next/standalone. Deze map is bedoeld om zelfstandig te implementeren zonder extra node_modules afhankelijkheden.

Als u de standalone functie wilt inschakelen, voegt u de volgende extra eigenschap toe aan uw next.config.js:

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

U moet ook de build opdracht in het package.json bestand configureren om statische bestanden naar uw zelfstandige uitvoer te kopiëren.

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

Uw Next.js routering en middleware configureren voor implementatie naar Azure Static Web Apps

Uw Next.js-project kan worden geconfigureerd voor aangepaste verwerking van routes met omleidingen, herschrijven en middleware. Deze handlers worden vaak gebruikt voor verificatie, personalisatie, routering en internationalisatie. Aangepaste verwerking is van invloed op de standaardroutering van uw Next.js-site en de configuratie moet compatibel zijn met hosting in Static Web Apps.

Static Web Apps valideert dat uw Next.js site is geïmplementeerd door tijdens het bouwen een pagina aan uw site toe te voegen. De pagina heeft de naam public/.swa/health.htmlen Static Web Apps controleert of uw site is opgestart en geïmplementeerd door te navigeren naar /.swa/health.html en te controleren of het antwoord is geslaagd. Middleware en aangepaste routering, waaronder omleidingen en herschrijven, kunnen van invloed zijn op de toegang van het /.swa/health.html pad, waardoor validatie van de implementatie van Static Web Apps kan worden voorkomen. Voer de volgende stappen uit om middleware en routering te configureren voor een geslaagde implementatie in Static Web Apps:

1. Sluit routes uit die beginnen met .swa uw middleware.ts (of .js) bestand in de middlewareconfiguratie.

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

2. Configureer uw omleidingen om next.config.js routes uit te sluiten die beginnen met .swa

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

3. Herschrijven configureren om next.config.js routes uit te sluiten die beginnen met .swa

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

Met deze codefragmenten worden paden uitgesloten die beginnen met .swa het verwerken van uw aangepaste routering of middleware. Deze regels zorgen ervoor dat de paden worden omgezet zoals verwacht tijdens de implementatievalidatie.

Logboekregistratie inschakelen voor Next.js

Volg de aanbevolen procedures voor het oplossen van problemen met Next.js server-API en voeg logboekregistratie toe aan de API om deze fouten te ondervangen. Logboekregistratie in Azure maakt gebruik van Application Insights. Als u deze SDK vooraf wilt laden, moet u een aangepast opstartscript maken. Zie voor meer informatie:

• Voorbeeld van een preloadscript voor Application Insights + Next.js
• GitHub-probleem
• Vooraf laden met Next.js

Resources opschonen

Als u deze toepassing verder niet gaat gebruiken, kunt u het Azure Static Web Apps-exemplaar verwijderen door de volgende stappen te volgen:

1. Open de Azure Portal.
2. Zoek in de bovenste zoekbalk naar mijn-eerste-statische-web-app.
3. Selecteer de naam van de app.
4. Selecteer Verwijderen.
5. Selecteer Ja om de verwijderactie te bevestigen (deze actie kan even duren).

Volgende stappen

App-instellingen configureren