MODO EDIÇÃO · Clique em qualquer texto · Ctrl+S salva · E sai
GREENS ORGANIZATION

NOVA
/ STACK

Fastify Boilerplate — A fundação padrão para novos serviços

11 MAR 2026 · PITCH TÉCNICO →
01 / 11
01
CONTEXTO

Por que precisamos
de um boilerplate?

motivo 01

Projetos sem padrão geram inconsistências entre times e dificultam o onboarding de novos devs.

motivo 02

Setup repetitivo a cada novo serviço: lint, CI, testes, segurança e Docker configurados do zero toda vez.

motivo 03

Boas práticas de segurança, error handling e conventional commits ficam de fora nos projetos "rápidos".

02 / 11
02 · ARQUITETURA

Fluxo de camadas

Clean Architecture aplicado: dependências sempre apontam para o centro. O /core não conhece framework, runtime ou banco — cada camada tem uma única responsabilidade.

CLIENT
──▶ Requisição HTTP chega ao servidor Fastify
/main·Interface Adapters
ROUTE
──▶ Mapeamento de endpoint + validação Zod na entrada
HANDLER
──▶ Orquestra a requisição e formata a resposta HTTP
↕ dependências apontam para dentro · fronteira DI
/core·Use Cases + Entities
SERVICE
──▶ Lógica de negócio — retorna Either<AppError, T>
/infra·Frameworks & Drivers
REPOSITORY
──▶ Acesso ao banco via Knex — zero lógica de negócio
POSTGRESQL
──▶ Persistência · versão 16+ · migrations controladas
03 / 12
03 · AGNÓSTICO

Agnóstico por design

O /core não conhece framework, runtime ou banco. A substituição é cirúrgica — só a camada correspondente muda.

RUNTIME
Bun
↕
Node.js ≥22
zero mudança no código
FRAMEWORK
Fastify
↕
Hono
só /main muda
DATABASE
PostgreSQL
↕
MySQL
só /infra muda
/core permanece intacto em qualquer substituição — é o contrato, não a implementação

CLEAN ARCHITECTURE · Robert C. Martin — dependências sempre apontam para o centro

04 / 12
04 · STACK

Tecnologias escolhidas

FRAMEWORK
Fastify
Alta performance, schema-first, plugin ecosystem maduro
LINGUAGEM
TypeScript
Strict mode ativo — tipos como contrato, não decoração
RUNTIME
Bun / Node.js
Dual runtime: Bun para máxima velocidade, Node ≥22 como fallback
VALIDAÇÃO
Zod
Schemas TypeScript-first validando na borda da aplicação
BANCO
PostgreSQL + Knex
PG 16+ com query builder tipado e migrations versionadas
TESTES & HTTP
Vitest + Ky
Test runner moderno + HTTP client para testes de integração
05 / 12
05 · ESTRUTURA

Organização do código

Três módulos de alto nível com responsabilidades bem definidas. Sem cross-contamination entre camadas.

src/core/

Lógica de domínio pura. Sem dependências de framework ou infra.

src/infra/

Implementações concretas. Knex, Pino, OpenTelemetry e integrações externas.

src/main/

Ponto de entrada. DI wiring, roteamento e inicialização do servidor.

06 / 12
06 · ERRORS

Erros como
valores tipados

Sem try/catch espalhados pelo código. O tipo de retorno força o tratamento do erro em todo call site.

  • Erro nunca passa despercebido — TypeScript exige tratamento
  • Mensagens padronizadas com App Error
  • Handlers formatam a resposta HTTP a partir do tipo de erro
  • Totalmente testável sem mocking de exceções
// src/core/errors/index.ts — framework-agnostic export class AppError extends Error { readonly code: ErrorCode readonly statusCode: number constructor(code: ErrorCode, message: string) { super(message) this.code = code this.statusCode = codeToStatus(code) } } // code → HTTP status, definido uma vez, reutilizado em todo lugar const codeStatusMap: Record<ErrorCode, number> = { NOT_FOUND: 404, CONFLICT: 409, UNAUTHORIZED: 401, INTERNAL_SERVER_ERROR: 500, }
// src/core/errors/index.ts — o contrato Either export type Either<L, R> = | { success: false; error: L } | { success: true; data: R } export function left<L>(error: L): Either<L, never> { return { success: false, error } } export function right<R>(data: R): Either<never, R> { return { success: true, data } } // SchemaError estende AppError — erros de validação Zod export class SchemaError extends AppError { static fromZod(e: ZodError): SchemaError { const msgs = e.issues.map(i => `${i.path.join('.')}: ${i.message}`).join(';') return new SchemaError(msgs) } }
// src/core/services/user/user-service.ts async createUser( input: CreateUserInput ): Promise<Either<AppError, User>> { const exists = await this.userRepository .findByEmail(input.email) if (exists) { return left(new AppError( 'CONFLICT', 'Email already in use' )) } return right( await this.userRepository.create(input) ) }
// src/main/routes/v1/user/index.ts — unwrap na rota function unwrap<T>(result: Either<unknown, T>): T { if (!result.success) throw result.error return result.data } // src/main/infra/error-handler.ts — captura central if (error instanceof AppError) { return reply.status(error.statusCode).send({ code: error.code, message: error.message, requestId: request.id, }) } if (error instanceof ZodError) { return reply.status(400).send({ code: 'BAD_REQUEST', message: SchemaError.fromZod(error).message, }) }
07 / 12
07 · QUALIDADE

Guardrails automáticos

Biome
LINTER + FORMATTER
Substitui ESLint + Prettier. Rápido, zero config, opinativo. Roda no pre-commit via Husky.
Vitest
TESTES UNITÁRIOS & INTEGRAÇÃO
Cobertura completa exigida antes de todo push. Integrado com Ky para testes de HTTP end-to-end.
Semgrep SAST
ANÁLISE DE SEGURANÇA ESTÁTICA
Detecta vulnerabilidades automaticamente no CI. Código inseguro não chega em main.
Husky + GH Actions
CI/CD LOCAL + REMOTO
Hooks locais bloqueiam antes do push. Pipeline remoto garante qualidade antes de todo merge.
08 / 12
08 · DEPLOY

Dual Runtime
Support

Escolha o runtime que faz mais sentido pro ambiente. O código-fonte é idêntico nos dois casos.

BUN
~133 MB · imagem Docker Distroless
  • Hot reload nativo sem configuração
  • Performance superior em I/O
  • Imagem menor e mais segura
NODE.JS
~192 MB · imagem Docker Alpine
  • Node ≥22 com tsx para dev
  • Compatibilidade máxima com o ecossistema
  • Fallback estável e bem testado
09 / 12
09 · FLUXO

Pipeline & Git Flow

Toda mudança passa por duas camadas de verificação automática:

LOCAL
git commit
→
Husky
→
Biome
→
TypeScript
→
Vitest
REMOTO
Pull Request
→
GH Actions
→
Biome
→
Semgrep
→
Vitest
→
Merge
Git Flow

Feature branches → develop → main. Ambas as branches protegidas, merge somente via PR aprovado.

Conventional Commits

feat:, fix:, chore: — histórico legível e changelogs automáticos gerados a partir dos commits.

10 / 12
10 · ADOÇÃO

Como começar hoje

01
Clone o repositório
git clone https://github.com/Greens-Organization/fastify-boilerplate
02
Configure o ambiente
cp .env.example .env && bun install && bun run docker:db:up
03
Rode as migrations e inicie
bun run db:migrate:latest && bun run dev:bun
04
Verifique que tudo passa
bun run test && bun run lint
11 / 12
11 · FIM

VAMOS
CONSTRUIR
MELHOR.

Padronização, qualidade e velocidade — desde o primeiro commit.

REPO github.com/Greens-Organization/fastify-boilerplate
STACK Fastify · TypeScript · Bun · PostgreSQL · Vitest
DATA 11 de Março de 2026