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 é habilitada, a CLI implanta seus ativos internos para Fabric e fornece uma URL pública em que os usuários podem acessar seu aplicativo.

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:

Executa o comando de build configurado (por exemplo, npm run build).
Valida se a pasta de saída existe e contém arquivos.
Empacota todos os arquivos em um arquivo ZIP compactado (no máximo 100 MB).
Carrega o arquivo para o host do Fabric Apps.
Retorna uma URL de hospedagem pública em que seu aplicativo está acessível.

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

Opções de configuração

Opção	Obrigatório	Default	Description
`enabled`	Sim	—	Defina como `true` para habilitar a hospedagem estática.
`folder`	Sim	—	Pasta de saída que contém os arquivos estáticos gerados, relativa a `root`.
`root`	No	raiz do projeto	Diretório raiz do projeto de frontend, relativo à raiz do projeto.
`buildCommand`	No	—	Comando shell a ser executado antes do empacotamento (por exemplo, `npm run build`).
`indexDocument`	No	—	Documento padrão a ser usado para solicitações de diretório (por exemplo, `index.html`).

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

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

Testar localmente

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

Crie seu front-end:
```
npm run build
```
Verifique se a pasta de saída contém os arquivos esperados:
```
ls dist
```
Sirva os arquivos criados com um servidor estático local:
```
npx serve dist
```
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.

Comentários

Esta página foi útil?

Last updated on 2026-06-02