Alojamento de conteúdos estáticos para aplicações Fabric

O Fabric Apps inclui um serviço de alojamento de conteúdos estáticos que constrói, empacota e serve a sua aplicação frontend juntamente com as APIs backend. Quando o alojamento estático está ativado, a CLI implementa os seus ativos construídos no Fabric e fornece uma URL pública onde os utilizadores podem aceder à sua aplicação.

Pré-requisitos

• Um projeto Fabric Apps com uma aplicação frontend (por exemplo, React, Vue ou o TypeScript padrão).
• Um comando build que produz saída estática (por exemplo, npm run build).

Como funciona o alojamento estático

Quando implementas com alojamento estático ativado, a CLI executa estes passos:

1. Executa o comando de build configurado (por exemplo, npm run build).
2. Valida que a pasta de saída existe e contém ficheiros.
3. Empacota todos os ficheiros num arquivo ZIP comprimido (máximo 100 MB).
4. Carrega o arquivo para o anfitrião do Fabric Apps.
5. Devolve uma URL de alojamento público onde a sua aplicação está acessível.

Configurar alojamento estático

Adicione uma staticHosting secção sob services no seu ficheiro rayfin/rayfin.yml:

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

Opções de configuração

Exemplo com um diretório frontend separado

Se o seu código frontend está num subdiretório:

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

Esta configuração resolve o caminho de saída para <project-root>/frontend/dist.

Implementação de conteúdo estático

Implantação completa

Quando executa npx rayfin up, o conteúdo estático é implementado automaticamente como parte da implementação full stack:

npx rayfin up

A CLI constrói o teu frontend, empacota a saída e carrega-a juntamente com a configuração do backend. Após a implementação, a CLI imprime a URL de alojamento e grava-a no seu .env.fabric-* ficheiro como VITE_RAYFIN_HOSTING_URL.

Implementação estática autónoma

Use o staticapp deploy subcomando para redistribuir apenas o seu conteúdo estático sem repetir a implementação completa:

npx rayfin up staticapp deploy

Este comando é útil quando só mudaste o código do frontend e queres um ciclo de iteração mais rápido.

Salta a etapa de construção

Se já construiu o seu frontend e quer implementar a saída existente sem reconstruir:

npx rayfin up staticapp deploy --skip-build

Ativar registo detalhado

Mostrar resultados detalhados durante a implantação:

npx rayfin up staticapp deploy --verbose

Configuração da chamada de retorno de autenticação

Quando tanto o alojamento estático como a autenticação estão ativados, o CLI Rayfin regista automaticamente um URI de retorno de autenticação com base no URL do seu alojamento.

Por exemplo, se o seu URL de alojamento for https://example.webapp.com, a CLI adiciona este URI de callback:

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

Não precisa de configurar manualmente o URI de callback de autenticação — a CLI atualiza a configuração e envia-a durante a implementação.

Limites de tamanho de implantação

• O arquivo ZIP comprimido não deve exceder 100 MB.
• A CLI utiliza compressão máxima para minimizar o tamanho de upload.
• Se o resultado da compilação exceder o limite, otimize os seus recursos da seguinte forma:
  • Excluindo os mapas de origem das builds de produção.
  • Comprimir ou remover imagens e vídeos grandes.
  • Mover ficheiros binários para o armazenamento do Fabric Apps em vez de os agrupar.

Exemplo completo

Uma configuração completa rayfin.yml com alojamento estático, autenticação e serviços de dados ativados:

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

Testar localmente

Antes de implementar, verifica se a tua build estática funciona localmente:

1. Construa o seu frontend:

   npm run build
   

2. Verifique se a pasta de saída contém os ficheiros esperados:

   ls dist
   

3. Servir os ficheiros compilados com um servidor estático local:

   npx serve dist
   

4. Abra o URL impresso pelo servidor e verifique se a sua aplicação carrega corretamente.

Solucionar problemas de implantação

Pasta estática não encontrada

Se a CLI reportar que a pasta estática não existe:

• Verifica se o folder caminho em rayfin.yml está correto e relativo a root (ou a raiz do projeto se root não estiver definido).
• Assegura-te de que o teu comando build correu com sucesso e produziu a saída no diretório esperado.

Pasta estática vazia

Uma pasta de saída vazia normalmente significa que o comando de compilação falhou ou não produziu saída. Execute manualmente o comando build para verificar erros:

npm run build

A implementação excede o limite de tamanho

Se o ZIP exceder 100 MB:

• Reveja o resultado da compilação para detetar ficheiros desnecessários (mapas de origem, recursos de desenvolvimento).
• Configura o teu bundler para excluir os mapas de origem em builds de produção.
• Mover ficheiros binários grandes para o armazenamento do Fabric Apps.

Nenhum endpoint remoto está configurado

O npx rayfin up staticapp deploy comando requer uma implantação remota já existente. Executa npx rayfin up primeiro para configurar o endpoint remoto e depois usa staticapp deploy para as atualizações seguintes.

Conteúdo relacionado

• Implementar no Fabric
• Configurar a autenticação
• Crie o seu primeiro projeto