5.9 KiB
Frontend
Você pode servir aplicações frontend estáticas com app.frontend() ou router.frontend().
Isso é útil para ferramentas de frontend que geram arquivos estáticos, como React com Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid e outras.
Com essas ferramentas, normalmente há uma etapa que faz o build do frontend, com um comando como:
npm run build
Isso geraria um diretório como ./dist/ com seus arquivos de frontend.
Você pode usar app.frontend() para servir esse diretório seguindo as convenções necessárias por esses frameworks de frontend.
FastAPI verifica as operações de rota primeiro. Os arquivos de frontend são verificados somente se nenhuma rota normal corresponder, então sua API não será afetada.
Sirva um Frontend
Depois de fazer o build do seu frontend, por exemplo com npm run build, coloque os arquivos gerados em um diretório, por exemplo, dist.
A estrutura do seu projeto poderia ser assim:
.
├── pyproject.toml
├── app
│ ├── __init__.py
│ └── main.py
└── dist
├── index.html
└── assets
└── app.js
Então sirva-o com app.frontend():
{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *}
Com isso, um request para /assets/app.js pode servir dist/assets/app.js.
Se você também tiver uma operação de rota do FastAPI, a operação de rota tem prioridade.
Roteamento no Lado do Cliente
Muitas aplicações frontend, incluindo aplicações de página única (SPAs), usam roteamento no lado do cliente. Um path como /dashboard/settings pode não ser um arquivo real, mas o framework cuidaria de lidar com ele.
Então, ao acessar essa URL diretamente (em vez de navegar pela aplicação), o backend deveria servir a aplicação frontend a partir de index.html, para que o framework de frontend possa então lidar com o roteamento no lado do cliente.
Para isso, use fallback="index.html":
{* ../../docs_src/frontend/tutorial002_py310.py hl[5] *}
FastAPI usa esse fallback somente para requests GET e HEAD que parecem navegação do navegador. Arquivos ausentes como JavaScript, CSS e imagens ainda retornam 404.
Requests com outros métodos, como POST ou PUT, para paths que correspondem apenas ao fallback do frontend também retornam 404. Operações de rota regulares do FastAPI ainda têm prioridade maior que rotas de frontend.
/// tip | Dica
Por padrão, fallback tem o valor fallback="auto". Na maioria dos casos, você não precisará especificar fallback. Leia abaixo para detalhes.
///
Isso é o que você desejaria com muitas aplicações frontend que usam roteamento no lado do cliente, por exemplo, React com TanStack Router, Vue, Angular, SvelteKit ou Solid.
Página 404 Personalizada
Você também pode servir uma página estática 404.html para paths de frontend ausentes:
{* ../../docs_src/frontend/tutorial003_py310.py hl[5] *}
Essa response mantém um código de status 404.
Neste caso, FastAPI não servirá index.html para paths de frontend ausentes. Ele retornará o arquivo 404.html em vez disso.
/// tip | Dica
Por padrão, fallback tem o valor fallback="auto". Com isso, se um arquivo 404.html for encontrado, ele será usado automaticamente como fallback.
Então, normalmente você pode omitir o argumento fallback.
///
Isso é útil com ferramentas de frontend que geram arquivos HTML estáticos para cada página, como Astro.
Fallback Automático
Por padrão, app.frontend() usa fallback="auto".
Se houver um arquivo 404.html no diretório do frontend, paths de frontend ausentes servem esse arquivo com código de status 404.
Caso contrário, se houver um arquivo index.html, paths de navegação do navegador ausentes servem index.html, que é o que muitas aplicações frontend com roteamento no lado do cliente esperam.
Então, na maioria dos casos, você pode usar app.frontend("/", directory="dist") sem especificar o argumento fallback.
{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *}
Desative o Fallback
Se você não quiser servir um arquivo de fallback para paths de frontend ausentes, use fallback=None:
{* ../../docs_src/frontend/tutorial005_py310.py hl[5] *}
Então paths de frontend ausentes retornam o 404 normal.
Verifique o Diretório
Por padrão, app.frontend() verifica se o diretório existe quando a aplicação é criada.
Isso ajuda a identificar erros de configuração cedo. Por exemplo, se o diretório de saída do build do frontend estiver ausente, FastAPI gerará um erro na inicialização.
Se seus arquivos de frontend forem criados depois, por exemplo por uma etapa de build separada após o objeto da aplicação ser criado, defina check_dir=False:
{* ../../docs_src/frontend/tutorial006_py310.py hl[5] *}
Com check_dir=False, FastAPI não verificará o diretório quando a aplicação for criada. Se o diretório configurado ainda estiver ausente quando um request for processado, FastAPI gerará um erro nesse momento.
Use com APIRouter
Você também pode adicionar arquivos de frontend a um APIRouter e incluí-lo com um prefixo:
{* ../../docs_src/frontend/tutorial004_py310.py hl[6,7] *}
Neste exemplo, os paths de frontend são servidos em /app.
Quaisquer operações de rota regulares na aplicação ainda terão precedência, inclusive em outros routers.
Apenas Saída de Build Estático
app.frontend() serve arquivos já gerados pelo build do seu frontend.
Ele não executa renderização no lado do servidor. Ele é para frameworks de frontend que geram arquivos estáticos, não para frameworks que precisam de renderização dinâmica no servidor para cada request.