Guia do stack FARM: como criar apps full stack com FastAPI, React e MongoDB

O gerador de aplicativos full stack FastAPI, React, MongoDB (FARM) é uma ferramenta poderosa criada para agilizar a construção de aplicações web em ambiente de produção. Ao integrar FastAPI no back-end, React no front-end e MongoDB como banco NoSQL escalável, o gerador FARM permite que desenvolvedores Python criem rapidamente aplicações robustas com configuração mínima. Ideal para quem quer focar em funcionalidades, não em código boilerplate.

Este artigo apresenta o gerador FARM, explica seus principais recursos, traz instruções passo a passo de setup e mostra suas capacidades com um exemplo real: um aplicativo de gerenciamento de tarefas. Nosso objetivo é mostrar como o gerador simplifica o desenvolvimento full stack e dá poder a desenvolvedores Python para criar aplicações escaláveis e prontas para produção.

Se você precisa revisar MongoDB, confira o curso da DataCamp Introdução ao MongoDB em Python. 

O que é o gerador de aplicativos FastAPI?

O gerador FARM automatiza a criação de uma stack web completa com os seguintes componentes:

• Configuração full stack: Gera um back-end em FastAPI, um front-end em React e um banco MongoDB, tudo integrado para acelerar o desenvolvimento.
• Autenticação pré-configurada: Inclui OAuth2 com JWT, autenticação por magic link e gerenciamento de cookies para acesso seguro. OAuth2 com JWT funciona como um “passe VIP” (código JWT) que você recebe após o login para acessar áreas privadas.
• Integração com Docker Compose: Fornece arquivos Docker Compose pré-configurados para facilitar o desenvolvimento e os testes locais.
• Ferramentas operacionais: Incorpora Celery para processamento assíncrono de tarefas, Traefik para balanceamento de carga e GitHub Actions para CI/CD, garantindo um ambiente pronto para produção.

A lista completa de recursos está no repositório no GitHub.

Benefícios para desenvolvedores

O gerador FARM oferece vantagens importantes:

• Economia de tempo: Elimina tarefas repetitivas de setup, como configurar autenticação ou conexões de banco, permitindo começar a codar imediatamente.
• Boas práticas: Garante uma estrutura escalável, segura e de fácil manutenção, alinhada a padrões do mercado.
• Flexibilidade: Oferece uma base personalizável que você pode estender conforme as necessidades do projeto.

Como executar o gerador FastAPI do MongoDB

Para ilustrar as capacidades do gerador, vamos configurar um projeto de exemplo. As instruções a seguir assumem que você tem Python 3.8+, Node.js, Docker e Docker Compose instalados.

Instruções de setup passo a passo

Para demonstrar os recursos do gerador, vamos criar um projeto exemplo chamado task-manager. Garanta que os pré-requisitos abaixo estejam instalados:

• Python 3.11+: De preferência 3.12, verificado com python3.12 --version.
• Node.js: Para o front-end em React.
• Docker Desktop: Para desenvolvimento em contêineres.
• MongoDB: Instalação local (ex.: via Homebrew com brew install mongodb-community@7.0) ou MongoDB Atlas (use um URI como mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority).
• Cookiecutter: Para gerar o template do projeto.
• Hatch: Para gerenciamento de dependências.
• MongoDB Compass (opcional): Para visualizar o banco.

Antes de continuar, crie um ambiente virtual com /usr/local/bin/python3.12 -m venv task-manager-venv e ative com source task-manager-venv/bin/activate.

1. Instale a biblioteca cookiecutter: pip install cookiecutter
2. Gere o projeto: use o gerador FARM para criar um projeto:

cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb --no-input project_name="task-manager"
cd task-manager

3. Instale o MongoDB localmente ou use o MongoDB Atlas:

brew tap mongodb/brew
brew install mongodb-community@7.0
brew services start mongodb-community@7.0

No Atlas, cadastre-se, crie um cluster gratuito e obtenha uma string de conexão (ex.: mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority) para usar no seu arquivo .env.

4. Configure as variáveis de ambiente: 

Copie e edite o arquivo .env:

cp .env.example .env
nano .env

Atualize com seu URI do MongoDB, nome do banco e segredos:

MONGODB_URI=mongodb://localhost:27017
MONGO_DATABASE=task_manager
SECRET_KEY=your-secret-key
FIRST_SUPERUSER=admin@task-manager.com
FIRST_SUPERUSER_PASSWORD=changethis

5. Faça o build e rode com Docker Compose:

Garanta que o Docker Desktop está em execução e então:

docker compose build --no-cache

1. docker compose up -d
2. Acesse o aplicativo:
• Front-end: http://localhost:3000
• Back-end: http://localhost/api/v1
• Swagger UI: http://localhost/docs (documentação interativa da API)
• ReDoc: http://localhost/redoc
• Flower: http://localhost:5555 (monitoramento do Celery)
• Traefik UI: http://localhost:8090 (dashboard de roteamento)
3. Faça login com admin@task-manager.com (senha: changethis).
4. Teste a autenticação: use o Swagger UI (/docs) para testar os endpoints /auth/login ou /auth/magic-link.
5. Configure o CI/CD: faça push para o GitHub para acionar os workflows do GitHub Actions inclusos.

Explore a estrutura do projeto full stack gerado

Ao usar o gerador FARM, ele cria um projeto task-manager com tudo bem organizado. Pense como uma casa pronta, onde cada cômodo tem sua função:

• backend/: É a cozinha onde o back-end FastAPI trabalha. Tem pastas como app/ (seu código de API) e conf/ (configurações) para lidar com tarefas e dados.

• frontend/: É a sala de estar onde os usuários veem seu site, com Next.js/React. A pasta app/ reúne páginas (ex.: about, TaskList) com arquivos como layout.tsx (estrutura da página) e page.tsx (conteúdo). A pasta public/ guarda itens como o ícone do site.

• Outros arquivos: Você encontrará docker-compose.yml (para rodar tudo com Docker), .env (suas configurações secretas) e .github/workflows/ (para testes automáticos quando você compartilhar seu código).

Esse setup está pronto para crescer, e o gerador inclui ferramentas bem úteis para facilitar o desenvolvimento!

O que você pode fazer com os recursos do gerador

O gerador FARM vem com ferramentas excelentes para ajudar você a criar vários tipos de projetos. Aqui vai um panorama simples do que elas fazem e como ajudam:

Integração com Docker Compose: otimizada para desenvolvimento local

• O que faz: O Docker Compose é como um botão mágico que configura e executa seu projeto inteiro (back-end, front-end, banco) com um comando. Ele usa contêineres para isolar tudo e facilitar testes na sua máquina.
• Como ajuda: Você inicia seu app task-manager com docker compose up -d e encerra com docker compose down. É perfeito para experimentar sem bagunçar seu ambiente. Confira o status com docker compose ps—se tudo estiver “Up”, está valendo!

Exemplo: Depois do setup do projeto, rode:

cd task-manager
docker compose up -d

Abra http://localhost:3000 para ver o front-end rodando localmente!

Sistema de autenticação embutido

• O que faz: Adiciona um sistema de login com contas de usuário, incluindo um superusuário padrão (como admin@task-manager.com com senha changethis). Usa OAuth2 com tokens JWT (códigos de login seguros) e magic links (links por e-mail para entrar).
• Como ajuda: Você permite que usuários se cadastrem, façam login ou usem magic link para acessar o app. Teste em http://localhost/docs no Swagger UI—procure por /api/v1/login/oauth para simular o login. É ótimo para apps com conteúdo restrito, como uma lista de tarefas privada.

Exemplo: Faça login com o usuário padrão:

1. Acesse http://localhost/docs.
2. Encontre /api/v1/login/oauth, informe admin@task-manager.com e a senha, e clique em “Execute”. Você receberá um token JWT para usar em páginas privadas!

A API do task manager

Demo da API Oauth

Retorno da API Oauth

Recursos do back-end FastAPI

Vamos ver de perto os recursos-chave do back-end em FastAPI e como ele simplifica operações de banco, design de API e escalabilidade.

• MongoDB Motor: É o motor que conversa com o seu MongoDB muito rápido, mesmo sob muitas requisições.
• MongoDB ODMantic: Pense como um helper que facilita salvar e buscar dados no MongoDB, organizando as tarefas direitinho.
• Suporte a CRUD comum: CRUD significa criar, ler, atualizar e excluir. Esse recurso traz ferramentas prontas para adicionar, visualizar, alterar ou remover dados (como tarefas) sem começar do zero.
• Baseado em padrões: Segue OpenAPI e JSON Schema, deixando sua API clara e compatível com outras ferramentas e apps.
• Como ajuda: Você constrói rapidamente um back-end para armazenar tarefas. O gerador já prepara isso; basta adicionar suas ideias, como novos recursos, usando o código de base.

Exemplo: Adicione um visualizador rápido de tarefas em backend/app/api/tasks.py:

from fastapi import APIRouter, Depends
from odmantic import AIOEngine, Model
from motor.motor_asyncio import AsyncIOMotorClient
router = APIRouter(prefix="/tasks", tags=["tasks"])
class Task(Model):
    title: str
async def get_db():
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    return AIOEngine(client, database="task_manager")
@router.get("/")  # View all tasks
async def get_tasks(db: AIOEngine = Depends(get_db)):
    return await db.find(Task)

Teste em http://localhost/api/v1/tasks após reconstruir com docker compose up --build.

Front-end em Next.js/React

O front-end em React é onde os usuários interagem com seu app. Vamos ver a estrutura e as ferramentas que ajudam a criar páginas bonitas e responsivas.

• Autorização via middleware: Age como um porteiro, checando se o usuário está logado antes de ver certas páginas (ex.: apenas logados veem /TaskList).
• Validação de formulários com React Hook Form: Garante que formulários (como o de adicionar tarefa) tenham as informações certas antes de salvar, evitando tarefas vazias.
• Gerenciamento de estado com Redux: Controla o que está selecionado/visível, mantendo o app fluido mesmo com muitos dados.
• CSS e componentes com TailwindCSS, HeroIcons e HeadlessUI: Ferramentas de design prontas. TailwindCSS estiliza suas páginas, HeroIcons adiciona ícones e HeadlessUI traz botões e menus acessíveis.
• Como ajuda: Você constrói uma página de tarefas bonita, com formulários fáceis e acesso seguro. O gerador prepara o design; você foca nas funcionalidades.

Exemplo: Adicione um formulário simples em frontend/app/TaskList/page.tsx:

import { useState } from 'react';
export default function TaskList() {
  const [task, setTask] = useState({ title: '' });
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    fetch('http://localhost/api/v1/tasks', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(task),
    });
    setTask({ title: '' });
  };
  return (
    <div className="container mx-auto p-4">
      <h1 className="text-2xl font-bold">Add Task</h1>
      <form onSubmit={handleSubmit}>
        <input
          className="border p-2"
          value={task.title}
          onChange={e => setTask({ title: e.target.value })}
          placeholder="Task name"
        />
        <button className="bg-blue-500 text-white p-2" type="submit">Add</button>
      </form>
    </div>
  );
}

Visite http://localhost:3000/TaskList para adicionar uma tarefa.

Fazendo seu task manager crescer

O gerador dá um pontapé inicial sólido para um gerenciador de tarefas. Por exemplo, você pode:

• Adicionar um botão para marcar tarefas como concluídas usando as ferramentas de CRUD.
• Usar a autenticação para manter sua lista de tarefas privada.
• Estilizar com TailwindCSS para deixar tudo com ótimo visual.
• Configurar o Celery para enviar lembretes de tarefas por e-mail.

Outras ideias para explorar

Com esses recursos, dá para ir além de um gerenciador de tarefas:

• Blog ou site: Armazene posts no MongoDB, exiba com FastAPI e crie um site moderno com Next.js.
• Loja online: Salve produtos no MongoDB, processe pedidos com Celery e crie a vitrine com Next.js.
• Atualizações em tempo real: Mostre informações ao vivo (como placar de jogo) com MongoDB, recursos assíncronos do FastAPI e um dashboard em Next.js.

Conclusão

O gerador FARM simplifica o desenvolvimento full stack ao oferecer uma stack pré-configurada e pronta para produção que integra FastAPI, React e MongoDB. A automação do setup, a adesão a boas práticas e a arquitetura flexível tornam essa ferramenta valiosa para desenvolvedores Python. Seja construindo um task manager ou uma aplicação web complexa, o gerador FARM acelera o desenvolvimento e garante escalabilidade. Experimente agora seguindo as instruções de setup e explore a documentação completa no repositório do GitHub para liberar todo o seu potencial!

Quer se aprofundar? Confira estes recursos:

• Repositório oficial: Explore o código-fonte, leia a documentação completa, veja novidades ou contribua.
• Documentação do FastAPI: Saiba mais sobre os recursos do FastAPI e como ele sustenta o back-end.
• Curso de introdução ao FastAPI: Construa APIs robustas e em nível de produção com FastAPI, dominando operações HTTP, validação e execução assíncrona para criar pipelines eficientes de dados e ML.