Hosting di contenuto statico per app di Fabric

Fabric App include un servizio di hosting di contenuti statici che compila, crea pacchetti e gestisce l'applicazione front-end insieme alle API back-end. Quando l'hosting statico è abilitato, l'interfaccia della riga di comando distribuisce gli asset compilati in Fabric e fornisce un URL pubblico in cui gli utenti possono accedere all'applicazione.

Prerequisiti

  • Progetto app Fabric con un'applicazione front-end ( ad esempio React, Vue o vanilla TypeScript).
  • Comando di compilazione che produce output statico, ad esempio npm run build.

Funzionamento dell'hosting statico

Quando si esegue la distribuzione con hosting statico abilitato, l'interfaccia della riga di comando esegue questi passaggi:

  1. Esegue il comando di compilazione configurato, ad esempio npm run build.
  2. Verifica che la cartella di output esista e contenga file.
  3. Inserisce tutti i file in un archivio ZIP compresso (massimo 100 MB).
  4. Carica l'archivio nell'host app di Fabric.
  5. Restituisce un URL di hosting pubblico in cui l'applicazione è accessibile.

Configurare l'hosting statico

Aggiungere una sezione staticHosting sotto services nel file rayfin/rayfin.yml:

services:
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

Opzioni di configurazione

Opzione Obbligatorio Impostazione predefinita Description
enabled Sì — Impostalo su true per abilitare l'hosting statico.
folder Sì — Cartella di output contenente i file statici generati, relativa a root.
root No Radice del progetto Directory principale del progetto front-end, rispetto alla radice del progetto.
buildCommand No — Comando Shell da eseguire prima della creazione del pacchetto , ad esempio npm run build.
indexDocument No — Documento predefinito da gestire per le richieste di directory , ad esempio index.html.

Esempio con una directory front-end separata

Se il codice front-end si trova in una sottodirectory:

services:
  staticHosting:
    enabled: true
    root: frontend
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

Questa configurazione determina il percorso di output come <project-root>/frontend/dist.

Distribuire contenuto statico

Distribuzione completa

Quando si esegue npx rayfin up, il contenuto statico viene distribuito automaticamente come parte della distribuzione completa dello stack:

npx rayfin up

La CLI genera il frontend, impacchetta l'output e lo carica insieme alla configurazione del backend. Dopo la distribuzione, la CLI visualizza l'URL di hosting e lo scrive nel tuo file .env.fabric-* come VITE_RAYFIN_HOSTING_URL.

Distribuzione statica autonoma

Usare il staticapp deploy sottocomando per ridistribuire solo il contenuto statico senza eseguire nuovamente la distribuzione completa:

npx rayfin up staticapp deploy

Questo comando è utile quando è stato modificato solo il codice front-end e si vuole un ciclo di iterazione più veloce.

Ignora la fase di compilazione

Se il front-end è già stato compilato e si vuole distribuire l'output esistente senza ricompilare:

npx rayfin up staticapp deploy --skip-build

Abilitare la registrazione dettagliata

Mostra output dettagliato durante la distribuzione:

npx rayfin up staticapp deploy --verbose

Configurazione del callback di autenticazione

Quando l'hosting statico e l'autenticazione sono abilitati, l'interfaccia della riga di comando di Rayfin registra automaticamente un URI di callback di autenticazione in base all'URL di hosting.

Ad esempio, se l'URL di hosting è https://example.webapp.com, l'interfaccia della riga di comando aggiunge questo URI di callback:

services:
  auth:
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
      - https://example.webapp.com/auth/callback

Non è necessario configurare manualmente l'URI di callback di autenticazione. L'interfaccia della riga di comando aggiorna la configurazione ed esegue il push durante la distribuzione.

Limiti di dimensione della distribuzione

  • L'archivio ZIP compresso non deve superare i 100 MB.
  • L'interfaccia della riga di comando usa la compressione massima per ridurre al minimo le dimensioni di caricamento.
  • Se l'output di compilazione supera il limite, ottimizza le risorse in questo modo:
    • Esclusione delle source map dalle build di produzione.
    • Compressione o rimozione di immagini e video di grandi dimensioni.
    • Spostare i file binari nell'archiviazione delle app di Fabric invece di includerli nel bundle.

Esempio completo

Configurazione completa rayfin.yml con hosting statico, autenticazione e servizi dati abilitati:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    fabric:
      enabled: true
  data:
    enabled: true
    dialect: mssql
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

Testare localmente

Prima della distribuzione, verificare che la compilazione statica funzioni localmente:

  1. Compilare il front-end:

    npm run build

  2. Verificare che la cartella di output contenga i file previsti:

    ls dist

  3. Gestire i file compilati con un server statico locale:

    npx serve dist

  4. Aprire l'URL stampato dal server e verificare che l'applicazione venga caricata correttamente.

Risolvere i problemi relativi alla distribuzione

Cartella statica non trovata

Se l'interfaccia della riga di comando segnala che la cartella statica non esiste:

  • Verificare che il folder percorso in rayfin.yml sia corretto e relativo a root (o alla radice del progetto se root non è impostato).
  • Verificare che il comando di compilazione sia stato eseguito correttamente e prodotto l'output nella directory prevista.

Cartella statica vuota

Una cartella di output vuota indica in genere che il comando di compilazione non è riuscito o non ha prodotto l'output. Eseguire manualmente il comando di compilazione per verificare la presenza di errori:

npm run build

La distribuzione supera il limite di dimensioni

Se il file ZIP supera i 100 MB:

  • Esaminare l'output di compilazione per i file non necessari (mappe di origine, asset di sviluppo).
  • Configurare il bundler per escludere le mappe di origine nelle compilazioni di produzione.
  • Spostare file binari di grandi dimensioni nell'archiviazione di app di Fabric.

Nessun endpoint remoto configurato

Il npx rayfin up staticapp deploy comando richiede una distribuzione remota esistente. Eseguire npx rayfin up prima di tutto per configurare l'endpoint remoto, quindi usare staticapp deploy per gli aggiornamenti successivi.

Contenuti correlati

  • Last updated on