Hospedagem de conteúdo estático para aplicativos Fabric

Fabric Aplicativos inclui um serviço de hospedagem de conteúdo estático que compila, empacota e serve seu aplicativo de front-end junto com suas APIs de back-end. Quando a hospedagem estática está habilitada, a CLI implanta seus ativos construídos no Fabric e fornece uma URL de hospedagem. Você pode exigir que os usuários façam login e tenham permissão para visualizar o aplicativo Fabric, ou pode permitir acesso anônimo aos ativos hospedados.

Pré-requisitos

• Um projeto Fabric Apps com um aplicativo de front-end (por exemplo, React, Vue ou vanilla TypeScript).
• Um comando de build que produz saída estática (por exemplo, npm run build).

Como funciona a hospedagem estática

Quando você implanta com a hospedagem estática habilitada, a CLI executa estas etapas:

1. Executa o comando de build configurado (por exemplo, npm run build).
2. Valida se a pasta de saída existe e contém arquivos.
3. Empacota todos os arquivos em um arquivo ZIP compactado (no máximo 100 MB).
4. Carrega o arquivo para o host do Fabric Apps.
5. Aplica a configuração de acesso configurado e retorna uma URL de hospedagem.

Configurar a hospedagem estática

Adicione uma seção staticHosting em services no seu arquivo rayfin/rayfin.yml:

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

Opções de configuração

Configurar o acesso aos ativos hospedados

Defina assetAccess para um desses valores:

• protected- Exige que os usuários façam login e tenham permissão para visualizar o aplicativo Fabric antes de poderem recuperar os ativos hospedados.
• public - Permite que qualquer pessoa com a URL de hospedagem recupere ativos hospedados sem fazer login.

Hospedagem protegida controla o acesso aos arquivos estáticos que o Fabric Apps atende. Ele não substitui autenticação e autorização na sua aplicação ou APIs.

A primeira implantação interativa npx rayfin up solicitará que você escolha uma configuração de acesso se assetAccess não estiver configurada. Implantações não interativas usam protected e salvam essa configuração em rayfin.yml.

Para alterar a configuração de acesso após a implantação, atualize assetAccess, e então execute uma implantação completa:

npx rayfin up

O npx rayfin up staticapp deploy comando atualiza apenas o conteúdo. Não aplica um novo valor assetAccess.

Exemplo com um diretório de front-end separado

Se o código de front-end estiver em um subdiretório:

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

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

Implantar conteúdo estático

Implantação completa

Quando você executa npx rayfin up, o conteúdo estático é implantado automaticamente como parte da implantação de pilha completa:

npx rayfin up

A CLI cria seu front-end, empacota a saída e a carrega junto com sua configuração de back-end. Após a implantação, a CLI exibe a URL de hospedagem e a grava no arquivo .env.fabric-* como VITE_RAYFIN_HOSTING_URL.

Implantação estática independente

Use o staticapp deploy subcomando para reimplantar somente o conteúdo estático sem executar novamente a implantação completa:

npx rayfin up staticapp deploy

Esse comando é útil quando você só alterou o código de front-end e deseja um ciclo de iteração mais rápido.

Ignorar a etapa de build

Se você já compilou seu frontend e deseja implantar a saída existente sem compilá-la novamente:

npx rayfin up staticapp deploy --skip-build

Habilitar o registro em log detalhado

Mostrar saída detalhada durante a implantação:

npx rayfin up staticapp deploy --verbose

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

Quando a hospedagem estática e a autenticação estão habilitadas, a CLI do Rayfin registra automaticamente um URI de retorno de chamada de autenticação com base na URL de hospedagem.

Por exemplo, se a URL de hospedagem for https://example.webapp.com, a CLI adicionará este URI de retorno de chamada:

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

Você não precisa configurar o URI de retorno de chamada de autenticação manualmente – a CLI atualiza a configuração e a envia por push durante a implantação.

Limites de tamanho da implantação

• O arquivo ZIP compactado não deve exceder 100 MB.
• A CLI usa a compactação máxima para minimizar o tamanho do upload.
• Se a saída da compilação exceder o limite, otimize seus recursos fazendo o seguinte:
  • Excluindo mapas de origem de builds de produção.
  • Compactando ou removendo vídeos e imagens grandes.
  • Mover arquivos binários para o armazenamento do Fabric Apps em vez de incluí-los no pacote.

Exemplo completo

Uma configuração completa rayfin.yml com hospedagem estática, autenticação e serviços de dados habilitados:

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
    assetAccess: protected

Testar localmente

Antes de implantar, verifique se o build estático funciona localmente:

1. Crie seu front-end:

   npm run build
   

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

   ls dist
   

3. Sirva os arquivos criados com um servidor estático local:

   npx serve dist
   

4. Abra a URL impressa pelo servidor e verifique se o aplicativo é carregado corretamente.

Solucionar problemas de implantação

Pasta estática não encontrada

Se o CLI informar que a pasta `static` não existe:

• Verifique se o caminho folder em rayfin.yml está correto e é relativo a root (ou à raiz do projeto, se root não estiver definido).
• Verifique se o comando de build foi executado com êxito e produziu a saída no diretório esperado.

Pasta estática vazia

Uma pasta de saída vazia geralmente significa que o comando de build falhou ou não produziu a saída. Execute o comando de build manualmente para verificar se há erros:

npm run build

A implantação excede o limite de tamanho

Se o ZIP exceder 100 MB:

• Revise a saída da compilação em busca de arquivos desnecessários (mapas de origem, ativos de desenvolvimento).
• Configure seu empacotador para excluir mapas de origem em builds de produção.
• Mova arquivos binários grandes para Fabric Armazenamento de Aplicativos.

Nenhum endpoint remoto está configurado

O npx rayfin up staticapp deploy comando requer uma implantação remota existente. Execute npx rayfin up primeiro para configurar o ponto de extremidade remoto e, em seguida, use staticapp deploy para atualizações subsequentes.

Conteúdo relacionado

• Implantar no Fabric
• Configurar a autenticação
• Criar seu primeiro projeto