Como construí um blog com NextJS + NotionAPI

Stack e ferramentas utilizadas

• NextJS: Parte fundamental da minha stack como desenvolvedor, o Next.js oferece um ecossistema robusto e em constante evolução, apoiado por uma comunidade ativa. Suas funcionalidades de geração de conteúdo estático (SSG), renderização no servidor (SSR) e caching inteligente tornam o blog mais rápido, escalável e otimizado para SEO — pontos cruciais para qualquer aplicação moderna.

• NotionAPI oficial (@notionhq/client): Escolhi o Notion como CMS justamente porque já faz parte do workflow pessoal e profissional. Integrar a API permite que o fluxo de criação e gestão de conteúdo aconteça dentro da mesma ferramenta que uso para organizar minhas próprias tarefas e projetos, tantos os simples, quanto complexos. Isso elimina fricções, centraliza meu trabalho e ainda garante flexibilidade para escalar o blog sem depender de soluções externas de gestão de conteúdo.

• Lib notion-react-x: Optei por essa biblioteca porque ela facilita e agiliza o consumo dos dados expostos pela API do Notion, permitindo colocar o blog no ar rapidamente. Apesar de ser útil na fase inicial, encaro-a como uma solução temporária: a visão de longo prazo é evoluir para um nível de abstração em que o CMS seja apenas uma parte da engrenagem, podendo ser substituído conforme as necessidades do projeto.

• Lib notion-client (cliente não oficial): De forma complementar ao react-notion-x, utilizei essa biblioteca para tratar os dados da API do Notion e entregá-los prontos para renderização. Ela agiliza o desenvolvimento inicial, mas também será substituída futuramente à medida que o blog evoluir e ganhar uma camada própria de gerenciamento de dados, mais robusta e duradoura.

• Eslint e prettier: Embora sejam ferramentas distintas, elas atuam em conjunto para garantir qualidade e consistência no código. O ESLint ajuda a antecipar erros e potenciais bugs ainda na fase de desenvolvimento, enquanto o Prettier assegura que o estilo e a formatação sigam um padrão único. Dessa forma, mesmo que novas pessoas colaborem com o projeto no futuro, haverá uma base sólida de padronização que facilitará a manutenção e a evolução.

• NodeJS: Parte fundamental da minha stack, escolhi o Node.js pela facilidade de integração com todo o ecossistema da aplicação. Como tanto o Node quanto o Next.js são baseados em JavaScript, toda a solução “fala a mesma língua”, o que simplifica a comunicação entre camadas e acelera o desenvolvimento. Além disso, o próprio Next.js evoluiu apoiado no Node, o que reforça a sinergia entre as ferramentas.

• TypeScript: Embora a base seja JavaScript, optei por desenvolver o blog em TypeScript, um superset que adiciona tipagem estática à linguagem. Isso traz vantagens importantes como detecção antecipada de erros, escalabilidade, clareza na manutenção e até mesmo melhor documentação implícita do código, facilitando a colaboração e evolução do projeto futuramente.

• ExpressJS: Escolhi esse framework pela sua simplicidade e flexibilidade. Com poucas linhas de código é possível configurar um servidor robusto, capaz de escalar conforme as necessidades do projeto. Além disso, por ser um dos frameworks mais utilizados no ecossistema Node.js, conta com uma comunidade ampla e uma grande variedade de módulos complementares, o que acelera o desenvolvimento e reduz a necessidade de reinventar soluções.

• Vercel: Para o deploy do Next.js, optei pela Vercel, plataforma criada pela própria equipe responsável pelo framework. Essa escolha traz benefícios imediatos como deploy automatizado, funções serverless, computação de borda e uma infraestrutura totalmente otimizada para aplicações Next.js. Isso agiliza o desenvolvimento, melhora a performance e garante escalabilidade desde o início. Além disso, enquanto o blog não atinge um grande volume de tráfego, o plano gratuito é suficiente, permitindo manter a aplicação no ar sem custos iniciais de manutenção.

• AWS EC2: Em paralelo, utilizei a Amazon EC2, que também oferece um nível gratuito robusto e confiável. A plataforma proporciona flexibilidade total de configuração e controle sobre a infraestrutura, permitindo subir aplicações Node.js com poucos comandos. O console de gerenciamento é intuitivo, o que acelera o processo de provisionamento e torna a solução ideal para experimentação e aprendizado em ambientes de nuvem corporativa.

• Github: Além de hospedar o código do projeto, o GitHub funciona como uma vitrine do meu processo de desenvolvimento. A integração com o Git possibilita colaboração distribuída, gestão de histórico completo e segurança no controle de versões. A CLI torna o fluxo de publicação rápido e eficiente, e os recursos de repositório remoto asseguram alta disponibilidade e resiliência do código, independentemente do ambiente local.

• Nginx (Servidor Proxy): A escolha do Nginx demonstra preocupação tanto com desempenho quanto com segurança. Sua configuração simples permite utilizá-lo como proxy reverso, otimizando a entrega do conteúdo e preparando a aplicação para cenários de maior escala. Além disso, a facilidade para adicionar certificados SSL garante uma camada extra de proteção para os usuários desde os primeiros estágios do projeto.

• PM2 (gerenciador de processos): A adoção do PM2 tem como objetivo assegurar a alta disponibilidade da aplicação. Ele mantém o servidor sempre ativo, reiniciando automaticamente em caso de falhas inesperadas. Além disso, oferece recursos de monitoramento e balanceamento de carga, reforçando a confiabilidade da solução em ambientes reais de produção

Decisões técnicas e integrações

• Separação de camadas: mesmo com o suporte a rotas serverless no Next.js, optei por manter um backend em Node/Express para refletir arquiteturas reais de mercado e facilitar a evolução do sistema.

• CMS via Notion: uso diário no meu workflow e fácil integração via API, garantindo centralização do conteúdo e flexibilidade para futuras substituições.

• Monorepo: adotado para padronizar, evitar duplicações e permitir compartilhamento de código entre frontend e backend.

• CI/CD: Vercel para o frontend (deploy automatizado integrado ao GitHub) e GitHub Actions + runner self-hosted na EC2 para o backend, garantindo baixo custo e confiabilidade.

• Nginx e PM2: Nginx como proxy reverso com SSL e PM2 para manter a API sempre disponível, reiniciando em caso de falhas.

• Qualidade de código: TypeScript, ESLint e Prettier formam a base para padronização, prevenção de erros e manutenção futura.

Arquitetura e estrutura do projeto

Visão da arquitetura

Estrutura de pastas (Monorepo)

Design de API REST

• Rota GET /posts

app.get('/posts', async (req, res) => {
  try {
    const list = await getPostsList()
    return res.json(list)
  } catch (e) {
    console.error(e) // eslint-disable-line no-console
    return res.status(500).json({ error: 'Internal server error' })
  }
})

• Rota GET /post/:slug

app.get('/post/:slug', async (req, res) => {
  try {
    const { slug } = req.params

    const pageId = await getPostIdWithSlug({ slug })

    if (!pageId) return res.status(400).json({ message: 'Bad request' })

    const page = await getPostData({ pageId })

    if (!page) return res.status(404).json({ message: 'Post not found' })

    return res.json(page)
  } catch (e) {
    console.error(e) // eslint-disable-line no-console
    return res.status(500).json({ error: 'Internal server error' })
  }
})

Pipeline de Deploy (CI/CD)

1. Puxar a versão mais recente do código diretamente do repositório.

2. Construir a aplicação dentro de um container, garantindo consistência no ambiente de execução.

3. Reiniciar a aplicação automaticamente (com ajuda do PM2) para aplicar as mudanças sem downtime.

Desafios e soluções encontradas

• Integração com o Notion:
Desafio: A API do Notion é flexível, mas traz dados em formato complexo e pouco amigável para renderização direta.
Solução: Utilizei bibliotecas de apoio (notion-react-x e notion-client) para acelerar o desenvolvimento inicial, planejando substituí-las futuramente por uma camada própria de abstração.

• Estrutura em Monorepo:
Desafio: Organizar frontend e backend no mesmo repositório trouxe dificuldades na configuração de dependências e scripts de build.
Solução: Padronizei scripts e usei ferramentas de gerenciamento para manter consistência, além de documentar os processos para evitar retrabalho.

• Pipeline de Deploy
Desafio: Garantir automação de deploy sem custos adicionais e sem depender de fluxos manuais.
Solução: Combinei Vercel (frontend) com GitHub Actions + runner self-hosted (backend/EC2), mantendo baixo custo e confiabilidade.

• Manutenção da API
Desafio: Manter a aplicação sempre ativa em ambiente de produção, prevenindo falhas ou quedas inesperadas.
Solução: Adotei o PM2 como gerenciador de processos, garantindo reinício automático e monitoramento básico.

• Segurança e escalabilidade
Desafio: Desde o início, era importante pensar em HTTPS e em um caminho para lidar com aumento de tráfego.
Solução: Configurei o Nginx como proxy reverso, facilitando a adição de SSL e preparando o ambiente para cenários de maior demanda.

Roadmap e próximos passos

• Implementação de testes automatizados

• Uso de CDN para otimizar a entrega do conteúdo estático no frontend visando SEO.

• Melhoria de design para refletir um blog mais moderno

• Adicionar scripts de monitoramento de performance do conteúdo

• Utilização de ferramenta de bundle para diminuir o tamanho da aplicação devido ao monorepo

• Refatoração do código para desacoplar e preparar a aplicação para futuras substituições

Conclusão