Distribuire siti Web ibridi Next.js in App Web statiche di Azure (anteprima)

  • Articolo

In questa esercitazione si apprenderà come distribuire un sito Web Next.js in App Web statiche di Azure, usando il supporto per Next.js funzionalità come React Server Components, Server-Side Rendering (SSR) e route API.

Nota

Next.js supporto ibrido è disponibile in anteprima.

Prerequisiti

Funzionalità non supportate in anteprima

Le funzionalità seguenti di App Web statiche non sono supportate per Next.js con rendering ibrido:

  • API collegate che usano Funzioni di Azure, servizio app Azure, app Azure Container o azure Gestione API.
  • Emulazione e distribuzione locali dell'interfaccia della riga di comando SWA.
  • Supporto parziale per staticwebapp.config.json il file.
    • Il fallback di navigazione non è supportato.
    • Le riscritture di route alle route all'interno dell'applicazione Next.js devono essere configurate all'interno di next.config.js.
    • La configurazione all'interno del staticwebapp.config.json file ha la precedenza sulla configurazione all'interno next.config.jsdi .
    • La configurazione per il sito Next.js deve essere gestita usando next.config.js per garantire la compatibilità completa delle funzionalità.
  • skip_app_build e skip_api_build non possono essere usati all'interno dell'immagine di Azure/static-web-apps-deploy@v1 distribuzione.
  • La rigenerazione statica incrementale (ISR) non supporta la memorizzazione nella cache delle immagini.

Nota

La dimensione massima dell'app per l'applicazione ibrida Next.js è 250 MB. Usare la funzionalità autonoma Next.js per ottimizzare le dimensioni delle app. Se non è sufficiente, è consigliabile usare l'Next.js html statico esportato se il requisito di dimensioni dell'app è superiore a 250 MB.

Creare un repository

In questo articolo si usa un repository di modelli GitHub per semplificare le operazioni. Il modello include un'app iniziale da distribuire in App Web statiche di Azure.

  1. Passare al percorso seguente per creare un nuovo repository.

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

  2. Assegnare al repository il nome my-first-static-web-app

  3. Selezionare Create repository from template (Crea repository da modello).

    Screenshot del pulsante Crea repository dal modello.

Creare un'app Web statica

Dopo aver creato il repository, è possibile creare un'app Web statica dal portale di Azure.

  1. Vai al portale di Azure.
  2. Selezionare Crea una risorsa.
  3. Cercare App Web statiche.
  4. Selezionare App Web statiche.
  5. Seleziona Crea.

Per iniziare, nella sezione Informazioni di base configurare la nuova app e collegarla a un repository GitHub.

Screenshot della sezione Informazioni di base nella portale di Azure.

Impostazione Valore
Abbonamento Seleziona la tua sottoscrizione di Azure.
Gruppo di risorse Selezionare il collegamento Crea nuovo e immettere static-web-apps-test nella casella di testo.
Nome Immettere my-first-static-web-app nella casella di testo.
Tipo di piano Selezionare Gratuito.
Dettagli di Funzioni di Azure e della gestione temporanea Selezionare un'area più vicina.
Origine Selezionare GitHub.

Selezionare Accedi con GitHub ed eseguire l'autenticazione con GitHub.

Dopo aver eseguito l'accesso con GitHub, immettere le informazioni sul repository.

Impostazione Valore
Organizzazione Selezionare l'organizzazione.
Repository Selezionare my-first-web-static-app.
Filiale Selezionare main.

Screenshot dei dettagli del repository nel portale di Azure.

Nota

Se non vengono visualizzati repository:

  • Potrebbe essere necessario autorizzare App Web statiche di Azure in GitHub. Passare al repository GitHub e passare a Impostazioni > Applicazioni > autorizzate per le app OAuth, selezionare App Web statiche di Azure e quindi selezionare Concedi.
  • Potrebbe essere necessario autorizzare App Web statiche di Azure nell'organizzazione di Azure DevOps. Per concedere le autorizzazioni, è necessario essere un proprietario dell'organizzazione. Richiedere l'accesso alle applicazioni di terze parti tramite OAuth. Per altre informazioni, vedere Autorizzare l'accesso alle API REST con OAuth 2.0.

Nella scheda Dettagli compilazione aggiungere i dettagli di configurazione specifici del framework front-end preferito.

  1. Selezionare Next.js dall'elenco a discesa Build Presets (Set di impostazioni di compilazione ).

  2. Mantenere il valore predefinito nella casella Percorso app.

  3. Lasciare vuota la casella Percorso API.

  4. Lasciare vuota la casella Percorso artefatto app.

Selezionare Rivedi e crea.

Screenshot del pulsante Crea.

Visualizzare il sito Web

La distribuzione di un'app statica è un processo in due passaggi. Il primo crea le risorse di Azure sottostanti che costituiscono l'app. Il secondo è un flusso di lavoro che compila e pubblica l'applicazione.

Prima di poter passare al nuovo sito statico, la compilazione della distribuzione deve prima terminare l'esecuzione.

La finestra panoramica App Web statiche visualizza una serie di collegamenti che consentono di interagire con l'app Web.

Screenshot della finestra di panoramica di App Web statiche di Azure.

Selezionando il banner indicato, selezionare qui per controllare lo stato delle esecuzioni di GitHub Actions per passare all'esecuzione di GitHub Actions nel repository. Dopo aver verificato il completamento del processo di distribuzione, è possibile passare al sito Web tramite l'URL generato.

Una volta completato il flusso di lavoro di GitHub Actions, è possibile selezionare il collegamento URL per aprire il sito Web nella nuova scheda.

Configurare il progetto Next.js in locale per apportare modifiche

  1. Clonare il nuovo repository nel computer. Assicurarsi di sostituire <YOUR_GITHUB_ACCOUNT_NAME> con il nome dell'account.

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

  2. Aprire il progetto in Visual Studio Code o nell'editor di codice preferito.

Aggiungere dati sottoposti a rendering del server con un componente server

Per aggiungere dati di cui è stato eseguito il rendering del server nel progetto Next.js usando il router app, modificare un componente Next.js per aggiungere operazioni sul lato server per eseguire il rendering dei dati nel componente. Per impostazione predefinita, Next.js componenti sono componenti server di cui è possibile eseguire il rendering.

  1. Aprire il app/page.tsx file e aggiungere un'operazione che imposta il valore di una variabile, che viene calcolata sul lato server. Ad esempio, il recupero di dati o altre operazioni del server.

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

  2. Importarlo unstable_noStore da next/cache e chiamarlo all'interno del Home componente per assicurarsi che il rendering della route venga eseguito in modo dinamico.

    import { unstable_noStore as noStore } from 'next/cache';

export default function Home() {
    noStore();

    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        ...
    );
}

    Nota

    In questo esempio viene eseguito il rendering dinamico di questo componente per illustrare il rendering del server dell'ora corrente del server. Il modello Router app di Next.js consiglia di memorizzare nella cache le singole richieste di dati per ottimizzare le prestazioni dell'app Next.js. Altre informazioni sul recupero e la memorizzazione nella cache dei dati in Next.js.

  3. Aggiornare il Home componente in app/pages.tsx per eseguire il rendering dei dati sul lato server.

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

Aggiunta di una route API

Oltre ai componenti server, Next.js fornisce gestori di route che è possibile usare per creare route API all'applicazione Next.js. Queste API possono essere recuperate nei componenti client.

Iniziare aggiungendo una route API.

  1. Creare un nuovo file in app/api/currentTime/route.tsx. Questo file contiene il gestore di route per il nuovo endpoint API.

  2. Aggiungere una funzione del gestore per restituire dati dall'API.

    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. Creare un nuovo file in app/components/CurrentTimeFromAPI.tsx. Questo componente crea un contenitore per il componente client che recupera l'API dal browser.

  4. Aggiungere un componente client che recupera l'API in questo file.

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

Questo componente client recupera l'API con un useEffect hook React per eseguire il rendering del componente al termine del caricamento. La 'use client' direttiva identifica questo elemento come componente client. Per altre informazioni, vedere Componenti client.

  1. Modificare app/page.tsx per importare ed eseguire il rendering del CurrentTimeFromAPI componente client.

    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. Il risultato della route API viene visualizzato nella pagina.

Screenshot che mostra l'output della route API.

Configurare la versione di runtime per Next.js

Alcune versioni di Next.js richiedono versioni Node.js specifiche. Per configurare una versione specifica di Node, è possibile impostare la proprietà "engines" del package.json file per designare una versione.

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

Impostare le variabili di ambiente per Next.js

Next.js usa variabili di ambiente in fase di compilazione e in fase di richiesta per supportare sia la generazione di pagine statiche che la generazione dinamica di pagine con il rendering lato server. Impostare quindi le variabili di ambiente sia all'interno dell'attività di compilazione che di distribuzione e nelle variabili di ambiente della risorsa App Web statiche di Azure.

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

Abilitare la funzionalità autonoma

Quando le dimensioni dell'applicazione superano i 250 Mb, la funzionalità di traccia file di output Next.js consente di ottimizzare le dimensioni dell'app e migliorare le prestazioni.

Traccia file di output crea una versione compressa dell'intera applicazione con le dipendenze del pacchetto necessarie incorporate in una cartella denominata .next/standalone. Questa cartella deve essere distribuita autonomamente senza dipendenze aggiuntive node_modules .

Per abilitare la standalone funzionalità, aggiungere la proprietà aggiuntiva seguente all'oggetto next.config.js:

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

È anche necessario configurare il build comando nel package.json file per copiare i file statici nell'output autonomo.

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

Configurare il routing e il middleware Next.js per la distribuzione in App Web statiche di Azure

Il progetto Next.js può essere configurato in modo da avere una gestione personalizzata delle route con reindirizzamenti, riscritture e middleware. Questi gestori vengono comunemente usati per l'autenticazione, la personalizzazione, il routing e l'internazionalizzazione. La gestione personalizzata influisce sul routing predefinito del sito Next.js e la configurazione deve essere compatibile con l'hosting in App Web statiche.

App Web statiche verifica che il sito Next.js sia stato distribuito correttamente aggiungendo una pagina al sito in fase di compilazione. La pagina è denominata public/.swa/health.htmle App Web statiche verifica l'avvio e la distribuzione del sito correttamente passando a /.swa/health.html e verificando una risposta corretta. Il middleware e il routing personalizzato, che include reindirizzamenti e riscritture, possono influire sull'accesso del percorso, che può impedire la /.swa/health.html convalida della distribuzione di App Web statiche. Per configurare il middleware e il routing per una corretta distribuzione in App Web statiche, seguire questa procedura:

  1. Escludere le route che iniziano con .swa nel middleware.ts file (o .js) nella configurazione del middleware.

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

  2. Configurare i reindirizzamenti in next.config.js per escludere le route a partire da .swa

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

  3. Configurare le riscritture in next.config.js per escludere le route a partire da .swa

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

Questi frammenti di codice escludono percorsi che iniziano da .swa essere gestiti dal routing personalizzato o dal middleware. Queste regole assicurano che i percorsi vengano risolti come previsto durante la convalida della distribuzione.

Abilitare la registrazione per Next.js

Seguendo le procedure consigliate per la risoluzione dei problemi delle API del server Next.js, aggiungere la registrazione all'API per rilevare questi errori. La registrazione in Azure usa Application Insights. Per precaricare questo SDK, è necessario creare uno script di avvio personalizzato. Per altre informazioni, vedere:

Pulire le risorse

Se non si intende continuare a usare questa applicazione, è possibile eliminare l'istanza di App Web statiche di Azure seguendo questa procedura:

  1. Apri il portale di Azure.
  2. Cercare my-first-web-static-app nella barra di ricerca in alto.
  3. Selezionare il nome dell'app.
  4. Selezionare Elimina.
  5. Selezionare Sì per confermare l'azione di eliminazione. L'operazione potrebbe richiedere alcuni istanti.

Passaggi successivi

Configurare le impostazioni dell'app