Capítulo 10 — Qualidade, performance e observabilidade

🎯 Objetivos de aprendizagem¶

Ao final deste capítulo você será capaz de:

• Configurar o ESLint 9 em flat config (eslint.config.js) para uma API Node e para um projeto Vue, e combiná-lo com o Prettier sem que um desfaça o trabalho do outro.
• Escrever e executar testes automatizados da API com Vitest e supertest — a mesma pilha da Aula 13 do Nível 3 —, incluindo um teste de integração que sobe o Express de verdade, e medir a cobertura.
• Escrever testes de componente e de store com o Vitest e o Vue Test Utils.
• Explicar as três métricas do Core Web Vitals (LCP, INP e CLS) e medir uma página publicada com o Lighthouse no DevTools, na linha de comando e no CI.
• Aplicar melhorias concretas de performance — imagens, fontes, divisão de código, cache e compressão no nginx — e comprovar o ganho com uma medição antes e depois.
• Instrumentar erros de produção com o SDK do Sentry (Node e navegador) e produzir logs estruturados com o pino, com rotação no servidor.
• Configurar monitoramento de disponibilidade e publicar robots.txt e sitemap.xml corretos.

📋 Pré-requisitos¶

• [ ] unieventos-api (Express 5) e unieventos-web (Vue 3 + Vite) rodando localmente, com GET /health respondendo { "status": "ok" }.
• [ ] Os dois projetos publicados: o site em um endereço HTTPS e a API no Render ou no VPS com nginx (Capítulos 03, 05 e 06).
• [ ] Workflows do GitHub Actions funcionando no repositório (Capítulo 09).
• [ ] Node 22 LTS na máquina (node -v) e a API já com vitest e supertest instalados (Aula 13 do Nível 3); se ainda não estiverem, a §3.1 mostra o npm install.
• [ ] Uma conta de e-mail para criar contas gratuitas no Sentry e em um serviço de uptime.

No Capítulo 09 o GitHub Actions passou a testar e publicar o projeto sozinho a cada push, e ficou uma pergunta em aberto — grande: testar o quê? Um pipeline que roda npm test sem nenhum teste escrito é um carimbo verde que não significa nada. Hoje você preenche esse vazio com quatro instrumentos — linter, testes, Lighthouse e observabilidade — e transforma "o código está bom", "o site parece rápido" e "acho que está no ar" em números que você consegue mostrar para outra pessoa: medição de performance com valor antes e depois, e um painel que avisa quando a produção quebra. Este é o último capítulo técnico da trilha; o próximo trata de usar assistentes de IA sem terceirizar o seu aprendizado.

🗺️ Roteiro¶

1. Qualidade não é opinião¶

"O código está bom" e "o site está rápido" são frases sem valor até virarem número. Quatro instrumentos cobrem quatro perguntas diferentes, e é comum confundi-los:

Repare no que cada um não faz. O linter não sabe se a sua conta está errada; sabe que você declarou uma variável e não usou. O teste não sabe se o site é lento. O Lighthouse mede a página no seu laboratório, com rede simulada — não mede o usuário real no 4G de Sinop. E a observabilidade não previne erro nenhum: conta que o erro aconteceu, para quem e com qual entrada.

Um detalhe que separa quem programa há um mês de quem programa há um ano: os quatro são baratos de instalar e caros de instalar tarde. Configurar ESLint em um projeto de 40 arquivos leva dez minutos e gera três avisos; em um de 400 arquivos, gera oitocentos avisos e vira um dia de trabalho que ninguém quer fazer.

🧠 Você sabia? O Node passou a ter executor de testes embutido: o módulo node:test, estável desde a linha 20. Antes disso, todo projeto Node precisava de uma biblioteca externa (Mocha, Jest, AVA, Tape) e arrastava dezenas de dependências só para escrever um assert. Hoje node --test roda um arquivo de teste sem nenhum npm install. A trilha continua usando o Vitest na API — porque é ele que o Nível 3 instalou e é o mesmo executor do front —, mas saber que o runner nativo existe muda a resposta para "vale a pena testar este script de 40 linhas?".

2. ESLint 9 e Prettier¶

2.1 O que o linter faz¶

O ESLint lê o seu JavaScript, monta a árvore sintática do arquivo e aplica regras. Cada regra tem um nível: off, warn (aparece, não quebra o build) ou error (quebra). Ele pega três famílias de problema: erros que só apareceriam em produção (no-undef, no-unreachable, no-dupe-keys), maus hábitos (no-var, eqeqeq, prefer-const) e convenções de biblioteca (o plugin do Vue avisa quando falta :key em um v-for). O que ele não pega: lógica errada, senha no código, consulta SQL lenta. Linter é o primeiro filtro, não o único.

A versão 9 abandonou o .eslintrc com extends em cascata e adotou o flat config: um único eslint.config.js que exporta um array de objetos de configuração, aplicados de cima para baixo — o último que fala sobre uma regra vence. Não há mais herança mágica de pastas superiores, e cada objeto pode se limitar a certos arquivos com files.

2.2 Na API¶

cd ~/weblab/unieventos-api
npm install --save-dev eslint @eslint/js globals prettier eslint-config-prettier

unieventos-api/eslint.config.js

import js from '@eslint/js'
import globals from 'globals'
import prettier from 'eslint-config-prettier'

export default [
  // Um objeto só com "ignores" vale para o projeto inteiro.
  { ignores: ['node_modules/', 'coverage/', 'dist/'] },

  js.configs.recommended,

  {
    files: ['**/*.js'],
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: 'module',
      globals: { ...globals.node },
    },
    rules: {
      'no-var': 'error',
      'prefer-const': 'error',
      eqeqeq: ['error', 'always'],
      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      'no-console': ['warn', { allow: ['error'] }],
    },
  },

  { files: ['tests/**/*.js'], rules: { 'no-console': 'off' } },

  // Desliga toda regra que brigaria com o Prettier. PRECISA ser o último item.
  prettier,
]

Três decisões merecem explicação. globals.node informa que process, console e URL existem — sem isso, no-undef reclama de tudo (no front o equivalente é globals.browser). argsIgnorePattern: '^_' permite escrever (erro, req, res, _next) no middleware de erro do Express 5 sem que o _next, obrigatório na assinatura e inútil no corpo, vire erro. E 'no-console': 'warn' é um lembrete: na §7 os console.log da API viram chamadas ao pino.

2.3 No front Vue¶

cd ~/weblab/unieventos-web
npm install --save-dev eslint @eslint/js globals eslint-plugin-vue prettier eslint-config-prettier

unieventos-web/eslint.config.js

import js from '@eslint/js'
import pluginVue from 'eslint-plugin-vue'
import globals from 'globals'
import prettier from 'eslint-config-prettier'

export default [
  { ignores: ['node_modules/', 'dist/', 'coverage/'] },
  js.configs.recommended,

  // O preset do Vue já configura o parser de arquivos .vue (vue-eslint-parser).
  ...pluginVue.configs['flat/recommended'],

  {
    files: ['**/*.{js,vue}'],
    languageOptions: { ecmaVersion: 2024, sourceType: 'module', globals: { ...globals.browser } },
    rules: {
      // As telas do UniEventos se chamam Eventos.vue, Login.vue…
      'vue/multi-word-component-names': 'off',
      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    },
  },

  prettier,
]

Repare nos três pontos de ...pluginVue.configs['flat/recommended']: o preset é um array de configurações, e o espalhamento coloca cada uma como item do array externo. Sem eles, o ESLint recebe um array dentro do array e falha ao carregar.

2.4 Prettier: quem decide a forma¶

O ESLint sabe formatar, mas formatar não é trabalho dele. A divisão que o mercado adotou é: Prettier decide a forma, ESLint decide o conteúdo. Repita o .prettierrc do Capítulo 01 na raiz de cada projeto e acrescente um .prettierignore com node_modules, coverage, dist e package-lock.json. O pacote eslint-config-prettier, importado como último item do array, desliga as regras de estilo do ESLint (indentação, aspas, vírgula final) que apontariam erro exatamente no formato que o Prettier acabou de aplicar — você já viu esse conflito se algum dia salvou um arquivo e o viu ser formatado e sublinhado de vermelho ao mesmo tempo.

Com tudo no lugar, o package.json da API ganha os scripts de qualidade:

unieventos-api/package.json (seção scripts)

{
  "scripts": {
    "dev": "node --watch --env-file=.env src/server.js",
    "start": "node src/server.js",
    "lint": "eslint . --max-warnings=0",
    "lint:corrigir": "eslint . --fix",
    "formatar": "prettier --write .",
    "formatar:conferir": "prettier --check .",
    "test": "vitest run",
    "test:observar": "vitest",
    "test:cobertura": "vitest run --coverage",
    "qualidade": "npm run lint && npm run formatar:conferir && npm test"
  }
}

npm run qualidade é o comando que você roda antes de abrir um pull request — e é exatamente o que o CI vai rodar. Quando os dois são o mesmo comando, ninguém é surpreendido pelo robô. O --fix resolve o mecânico (aspas, let que podia ser const) e deixa para você o que exige decisão: uma variável não usada pode ser lixo ou pode ser um bug.

🔎 Por baixo do capô O && entre os scripts não é decoração: ele encadeia processos e para no primeiro que devolver código de saída diferente de zero. Todo comando de terminal devolve esse código, e é assim que o GitHub Actions decide se um step passou. Teste: rode npm run lint em um projeto com erro e depois echo $? — vai imprimir 1. Depois de um comando bem-sucedido, 0.

⚠️ Atenção A extensão ESLint do VS Code usa o eslint.config.js da pasta aberta no editor. Se você abrir uma pasta que contém unieventos-web e unieventos-api lado a lado, ela procura um único arquivo na raiz e não acha nenhum dos dois. Abra um projeto por janela.

3. Testes da API com Vitest e supertest¶

3.1 O que testar quando o tempo é curto¶

A pilha de testes da API é a mesma desde a Aula 13 do Nível 3 — Vitest como executor e supertest para bater nas rotas —, e é a mesma do front (§4): um executor só para o projeto inteiro, uma configuração só, um npm test só. Se a sua API ainda não tem os dois:

cd ~/weblab/unieventos-api
npm install --save-dev vitest supertest @vitest/coverage-v8

💡 Dica Para projetos sem dependência nenhuma — um script de manutenção, um utilitário de linha de comando —, o Node 22 traz um runner embutido: import { describe, it } from 'node:test', import assert from 'node:assert/strict' e node --test para executar, sem npm install. A API da trilha fica no Vitest (é o que o Nível 3 instalou e o que o front usa), mas o node:test é a alternativa certa quando adicionar uma devDependency não compensa.

Você não vai testar tudo, e não precisa. A ordem que rende mais por hora investida: primeiro as funções puras com regra de negócio (paginação, cálculo de vagas, validação, normalização de texto) — baratas de testar e onde moram os bugs sutis; depois as rotas da API pelo contrato (o GET devolve 200 e um array? o POST sem título devolve 400 com mensagem?), que pegam quase todo erro de integração; e sempre a regra de ouro: todo bug corrigido vira um teste — antes de arrumar, escreva o teste que falha por causa dele.

O que não vale a pena no nosso tamanho: testar getters triviais, testar bibliotecas de terceiros e testar telas ponta a ponta (isso exige Playwright ou Cypress).

3.2 Teste de unidade¶

unieventos-api/src/util/paginacao.js

/** Recorta uma lista em páginas. Sempre devolve uma página válida, mesmo com entrada absurda. */
export function paginar(lista, pagina = 1, porPagina = 10) {
  const total = lista.length
  const paginas = Math.max(1, Math.ceil(total / porPagina))
  const atual = Math.min(Math.max(1, Number(pagina) || 1), paginas)
  const inicio = (atual - 1) * porPagina
  return { itens: lista.slice(inicio, inicio + porPagina), total, pagina: atual, paginas }
}

O teste vive em tests/, com a terminação .test.js — um dos padrões que o Vitest encontra sozinho:

unieventos-api/tests/paginacao.test.js

import { describe, it, expect } from 'vitest'
import { paginar } from '../src/util/paginacao.js'

const trinta = Array.from({ length: 30 }, (_, i) => ({ id: i + 1 }))

describe('paginar', () => {
  it('devolve os 10 primeiros itens na página 1', () => {
    const r = paginar(trinta, 1, 10)
    expect(r.itens).toHaveLength(10)
    expect(r.itens[0].id).toBe(1)
    expect(r.paginas).toBe(3)
    expect(r.total).toBe(30)
  })

  it('trata lista vazia sem quebrar', () => {
    const r = paginar([], 5, 10)
    expect(r.itens).toEqual([])
    expect(r.pagina).toBe(1)
    expect(r.paginas).toBe(1)
  })

  it('grampeia páginas fora do intervalo e entradas inválidas', () => {
    expect(paginar(trinta, 99, 10).pagina).toBe(3)
    expect(paginar(trinta, 'abacaxi', 10).pagina).toBe(1)
  })
})

toBe compara com Object.is (na prática, ===) e toEqual compara estruturas campo a campo. Prefira sempre a comparação estrita: em um expect('1').toEqual(1) o teste falha, e é isso que você quer — um teste que passa por engano é pior do que nenhum teste.

3.3 Teste de integração da rota¶

Este vale por dez: o supertest sobe o Express de verdade em uma porta livre, faz uma requisição HTTP real e derruba tudo no fim, sem você administrar servidor nem porta. Ele exige que src/app.js exporte o app sem chamar listen — a separação que a unieventos-api já tem desde o Nível 3 (export const app), e que existe justamente para isto; quem chama listen é o src/server.js.

unieventos-api/tests/eventos.test.js

import { describe, it, expect } from 'vitest'
import request from 'supertest'
import { app } from '../src/app.js'

describe('GET /api/eventos', () => {
  it('responde 200, JSON e uma lista', async () => {
    const resposta = await request(app).get('/api/eventos')

    expect(resposta.status).toBe(200)
    expect(resposta.headers['content-type']).toMatch(/application\/json/)
    expect(Array.isArray(resposta.body.itens)).toBe(true)
  })
})

describe('POST /api/eventos', () => {
  it('recusa evento sem título com 400 e mensagem', async () => {
    const resposta = await request(app)
      .post('/api/eventos')
      .send({ local: 'Anfiteatro' })

    expect(resposta.status).toBe(400)
    expect(resposta.body.erro).toMatch(/t[íi]tulo/i)
  })
})

O request(app) abre um servidor em uma porta efêmera, dispara a requisição e fecha tudo sozinho — testes nunca devem brigar por porta fixa. Quatro asserções cobrem o contrato inteiro de uma rota: código de status, tipo de conteúdo, formato do corpo e comportamento com entrada errada.

3.4 Executando e medindo cobertura¶

npx vitest run                     # roda tudo que parece teste e sai
npx vitest                         # modo interativo: reexecuta ao salvar
npx vitest run -t "paginar"        # só os testes cujo nome bate
npx vitest run --coverage          # com relatório de cobertura

vitest run executa uma vez e sai — é a forma que o CI precisa, porque o modo interativo nunca terminaria. A cobertura sai em tabela no fim, com a porcentagem de linhas, ramos e funções por arquivo e as linhas não cobertas. Use-a como mapa, não como meta: 100 % com asserções fracas não prova nada, e 60 % nas rotas certas já protege o essencial.

🔬 Investigue Rode npm run test:cobertura na sua API e olhe a coluna de linhas não cobertas do arquivo de rotas. Escolha uma linha não coberta que trate erro (um if de validação, um catch) e escreva o teste que a executa. Rode de novo e veja a porcentagem subir. Cronometre: quase sempre são menos de cinco minutos por teste — e essa é a resposta para "não tenho tempo de testar".

4. Testes de componente com Vitest¶

No front o executor é o mesmo — Vitest —, mas a configuração muda: ele reaproveita a do Vite (aliases, plugins, variáveis de ambiente) e precisa de um DOM de mentira para montar componentes Vue.

cd ~/weblab/unieventos-web
npm install --save-dev vitest @vue/test-utils jsdom @vitest/coverage-v8

unieventos-web/vitest.config.js

import { fileURLToPath } from 'node:url'
import { mergeConfig, defineConfig, configDefaults } from 'vitest/config'
import viteConfig from './vite.config.js'

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // jsdom simula document/window dentro do Node: é o "navegador de mentira".
      environment: 'jsdom',
      globals: true,
      setupFiles: ['./vitest.setup.js'],
      exclude: [...configDefaults.exclude, 'e2e/**'],
      root: fileURLToPath(new URL('./', import.meta.url)),
    },
  }),
)

unieventos-web/vitest.setup.js

// O Vuetify observa o tamanho dos elementos; o jsdom não implementa ResizeObserver.
// Sem este substituto, montar qualquer componente Vuetify quebra com ReferenceError.
global.ResizeObserver = class {
  observe() {}
  unobserve() {}
  disconnect() {}
}

unieventos-web/src/components/__tests__/EventoCard.spec.js

import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import { createVuetify } from 'vuetify'
import * as components from 'vuetify/components'
import * as directives from 'vuetify/directives'
import EventoCard from '../EventoCard.vue'

const vuetify = createVuetify({ components, directives })

function montar(evento) {
  return mount(EventoCard, { global: { plugins: [vuetify] }, props: { evento } })
}

describe('EventoCard', () => {
  it('mostra o título e o local do evento', () => {
    const wrapper = montar({ id: 1, titulo: 'Semana Acadêmica', local: 'Anfiteatro', vagas: 30 })
    expect(wrapper.text()).toContain('Semana Acadêmica')
    expect(wrapper.text()).toContain('Anfiteatro')
  })

  it('desabilita a inscrição quando não há vagas', () => {
    const wrapper = montar({ id: 2, titulo: 'Oficina de Cafés', local: 'Lab 3', vagas: 0 })
    expect(wrapper.get('button').attributes('disabled')).toBeDefined()
  })

  it('emite "inscrever" com o id ao clicar', async () => {
    const wrapper = montar({ id: 7, titulo: 'Palestra', local: 'Auditório', vagas: 5 })
    await wrapper.get('button').trigger('click')
    expect(wrapper.emitted('inscrever')[0]).toEqual([7])
  })
})

Uma store da Pinia se testa do mesmo jeito, sem rede: setActivePinia(createPinia()) em um beforeEach (cada teste precisa começar com estado limpo), depois atribua store.eventos na mão e verifique os getters. É o teste mais barato do front e pega quase todo erro de filtro e de total.

Scripts do front: "test:unit": "vitest run", "test:observar": "vitest", "test:cobertura": "vitest run --coverage" e um qualidade encadeando lint, formatação e testes. O vitest sem argumento entra em modo interativo e reexecuta ao salvar; vitest run executa uma vez e sai — é a forma que o CI precisa, porque o modo interativo nunca terminaria.

5. Core Web Vitals e Lighthouse¶

5.1 As três métricas¶

O Google padronizou três medidas de experiência real, os Core Web Vitals, escolhidas porque respondem a três perguntas que o usuário faz sem perceber:

Os limites valem para o percentil 75 dos carregamentos: três de cada quatro visitas precisam ficar na faixa boa. O INP substituiu o antigo FID, que media só o atraso da primeira interação — um número fácil de acertar e que escondia páginas travadas do segundo clique em diante.

Há duas fontes de dado, bem diferentes. Laboratório: o Lighthouse roda a página na sua máquina, com CPU e rede simuladas — reproduzível, imediato e não representa ninguém em particular. Campo: medições de visitantes reais; o PageSpeed Insights mostra os dados do CrUX quando o site tem tráfego suficiente, o que provavelmente não é o caso do seu projeto de estudo (para coletar os seus, use a biblioteca web-vitals). O Lighthouse não consegue medir INP em laboratório — não há usuário clicando — e usa o TBT (Total Blocking Time) como aproximação; a nota de 0 a 100 é uma média ponderada em que TBT, LCP e CLS pesam mais, e por isso um site com JavaScript pesado perde pontos mesmo pintando rápido.

🧠 Você sabia? A pontuação de performance do Lighthouse é comparativa: posiciona o seu site em uma curva construída a partir de milhões de páginas reais. Por isso ela é implacável na faixa alta — sair de 90 para 95 costuma dar mais trabalho do que sair de 40 para 70. E por isso a nota varia entre execuções na mesma página: rede, CPU disponível e até uma extensão do navegador mudam o resultado. Rode três vezes e use a mediana; o Lighthouse CI faz isso por você.

5.2 Medindo de três formas¶

No DevTools: aba Lighthouse → Mobile → Analyze page load. Bom para explorar, porque cada item reprovado abre com explicação e lista de arquivos.

Na linha de comando, que é o que permite guardar um relatório e comparar depois:

npx lighthouse@latest https://eventos.seudominio.dev \
  --only-categories=performance,accessibility,best-practices,seo \
  --output=html --output=json --output-path=./relatorios/antes \
  --chrome-flags="--headless" --quiet

Isso grava relatorios/antes.report.html (para abrir no navegador) e antes.report.json (para extrair números). Sem --preset=desktop, o Lighthouse simula um celular mediano com rede lenta — que é o cenário certo para a maioria de quem acessa pela primeira vez.

No CI, com o Lighthouse CI, que roda várias vezes, tira a mediana e reprova o build se a nota cair:

unieventos-web/lighthouserc.json

{
  "ci": {
    "collect": {
      "startServerCommand": "npm run preview",
      "url": ["http://localhost:4173/", "http://localhost:4173/eventos"],
      "numberOfRuns": 3
    },
    "assert": {
      "preset": "lighthouse:no-pwa",
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 0.9 }]
      }
    },
    "upload": { "target": "temporary-public-storage" }
  }
}

npm install --save-dev @lhci/cli
npm run build
npx lhci autorun

O autorun sobe o servidor de preview, roda o Lighthouse três vezes em cada URL, compara com as asserções e imprime um link público temporário para o relatório. No GitHub Actions vira um workflow:

.github/workflows/qualidade.yml

name: qualidade

on:
  push:
    branches: [main]
  pull_request:

jobs:
  verificar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run formatar:conferir
      - run: npm run test:unit
      - run: npm run build
      - run: npx lhci autorun

6. Sete melhorias que mudam o número¶

Não adianta otimizar no escuro. A ordem abaixo é a que mais rende em projetos do nosso tamanho, e cada item diz qual métrica ele move.

1. Dimensione e converta as imagens (LCP). Uma foto de 3000 px exibida em uma caixa de 600 px transfere nove vezes mais bytes do que precisa. Redimensione para o dobro da largura de exibição (por causa das telas de alta densidade), converta para WebP ou AVIF e sirva com <picture>:

unieventos-web/src/components/Hero.vue (trecho do template)

<picture>
  <source srcset="/img/hero-1200.avif" type="image/avif" />
  <source srcset="/img/hero-1200.webp" type="image/webp" />
  <img
    src="/img/hero-1200.jpg"
    alt="Estudantes na abertura da Semana Acadêmica"
    width="1200"
    height="600"
    fetchpriority="high"
  />
</picture>

2. Declare width e height em toda imagem (CLS). Sem elas o navegador reserva zero altura, pinta o texto e empurra tudo para baixo quando a imagem chega. Os atributos não fixam o tamanho visual (o CSS continua mandando com width: 100%; height: auto); informam a proporção, e o navegador reserva o espaço certo.

3. loading="lazy" fora da dobra, nunca na imagem do LCP. Imagens que só aparecem depois de rolar ganham loading="lazy"; a principal do topo recebe o oposto, fetchpriority="high" e nenhum lazy. Adiar a imagem do LCP é o erro de otimização mais comum — piora justamente a métrica que você queria melhorar.

4. Controle as fontes (LCP e CLS). Fonte externa bloqueia texto. No <head>:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet" />

O display=swap manda mostrar o texto imediatamente com a fonte de sistema e trocar quando a personalizada chegar. Melhor ainda: baixe os .woff2 para public/fontes/, declare @font-face com font-display: swap e um <link rel="preload" as="font" crossorigin> — some duas conexões externas e um risco a menos de indisponibilidade.

5. Divida o JavaScript por rota (TBT/INP). No Vue Router, troque a importação estática pela dinâmica: o Vite gera um arquivo por rota e o navegador só baixa a tela que o usuário abriu.

unieventos-web/src/router/index.js

import { createRouter, createWebHistory } from 'vue-router'
import Inicio from '../views/Inicio.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    // A tela inicial vem no pacote principal: é sempre a primeira a abrir.
    { path: '/', name: 'inicio', component: Inicio },
    // As demais viram arquivos separados, baixados sob demanda.
    { path: '/eventos', name: 'eventos', component: () => import('../views/Eventos.vue') },
    { path: '/eventos/:id', name: 'evento', component: () => import('../views/Evento.vue') },
    { path: '/admin', name: 'admin', component: () => import('../views/Admin.vue') },
  ],
})

export default router

Rode npm run build antes e depois: a saída do Vite lista o tamanho de cada arquivo gerado, e você vê o pacote principal encolher.

6. Cabeçalhos de cache no nginx (visitas seguintes). O Vite coloca um hash no nome de cada arquivo gerado (index-B7fK2p.js). Como o nome muda sempre que o conteúdo muda, esses arquivos podem ser guardados por um ano sem risco. O index.html, que aponta para eles, não pode ser guardado nunca.

/etc/nginx/sites-available/unieventos (trecho do server)

location ~* \.(?:js|css|woff2|png|jpg|jpeg|webp|avif|svg|ico)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

location = /index.html {
    add_header Cache-Control "no-cache";
}

7. Compressão (todas as métricas de rede). Texto comprime muito: um pacote de 300 KB costuma virar 90 KB com gzip.

/etc/nginx/nginx.conf (dentro do bloco http)

gzip on;
gzip_vary on;
gzip_comp_level 5;
gzip_min_length 256;
gzip_proxied any;
gzip_types text/plain text/css text/xml application/javascript application/json application/xml image/svg+xml;

text/html não entra na lista porque o nginx sempre o comprime. Não comprima imagens: JPEG, PNG e WebP já são formatos comprimidos, e passar gzip neles gasta CPU para economizar quase nada. O Brotli comprime cerca de 15 % melhor em texto, mas não vem no nginx padrão: depende do módulo ngx_brotli, que algumas distribuições empacotam e outras exigem compilar. Se a sua não tem, siga com gzip. Em Netlify, Vercel, Cloudflare Pages e GitHub Pages a compressão já vem ligada e negociada automaticamente.

sudo nginx -t && sudo systemctl reload nginx
curl -sI -H 'Accept-Encoding: gzip, br' https://eventos.seudominio.dev/assets/index.js | grep -i -E 'content-encoding|cache-control'

🔬 Investigue Rode o curl acima em três sites: o seu, o do WebLab e o portal da sua universidade ou escola. Compare content-encoding e cache-control. Depois, no DevTools → Network, clique em um arquivo .js e compare Size (o que trafegou) com o tamanho descomprimido: a razão entre os dois é a taxa de compressão. Qual dos três comprime melhor?

7. Observabilidade: Sentry e pino¶

7.1 Erros de produção¶

Em produção o console.log da API vai para um arquivo que ninguém lê, e o console.error do navegador morre no computador do usuário. Você fica sabendo do erro quando alguém reclama — se reclamar. Uma ferramenta de rastreamento inverte isso: o erro chega até você com pilha de chamadas, navegador, rota e quantas pessoas foram atingidas.

O Sentry tem plano gratuito suficiente para projetos de estudo. Crie a conta, crie dois projetos (um node e um vue) e guarde os dois DSN — a URL que identifica o projeto para onde os eventos são enviados.

cd ~/weblab/unieventos-api
npm install @sentry/node

O SDK precisa ser inicializado antes de qualquer outro import, porque instrumenta os módulos na hora em que são carregados. Por isso ele mora em um arquivo separado, carregado pelo Node antes do programa:

unieventos-api/instrument.js

import * as Sentry from '@sentry/node'

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV ?? 'development',
  release: process.env.APP_VERSION ?? 'dev',
  // Fração das requisições que vira "trace" de performance. 0.1 = 10 %.
  tracesSampleRate: 0.1,
  // Não envie IP, cookies nem corpo de requisição por padrão (LGPD).
  sendDefaultPii: false,
  // Sem DSN configurado, o SDK fica inerte — ótimo para rodar testes localmente.
  enabled: Boolean(process.env.SENTRY_DSN),
})

No package.json, o script start passa a carregá-lo: "start": "node --import ./instrument.js src/server.js". O --import executa o módulo antes do arquivo principal e é a forma recomendada com módulos ES. Depois de registrar todas as rotas, e antes do seu middleware de erro:

unieventos-api/src/app.js (trecho final)

// Captura as exceções que escaparem das rotas; vem ANTES do seu middleware de erro.
Sentry.setupExpressErrorHandler(app)

app.use((erro, req, res, _next) => {
  const status = erro.status ?? 500
  // Por enquanto, console.error; na §7.2 o pino-http cria req.log e esta
  // linha vira req.log.error({ err: erro }, 'erro não tratado').
  console.error('erro não tratado', erro)
  res.status(status).json({ erro: status === 500 ? 'Erro interno' : erro.message })
})

Lembre do Express 5: erros lançados dentro de handlers async vão automaticamente para o middleware de erro, sem .catch(next) — o que significa que o Sentry vê todos eles. Para algo que você tratou mas quer acompanhar, use Sentry.captureException(erro, { tags: { etapa: 'email-confirmacao' } }).

No front:

unieventos-web/src/main.js (trecho)

import * as Sentry from '@sentry/vue'

const app = createApp(App)

Sentry.init({
  app,
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,
  integrations: [Sentry.browserTracingIntegration({ router })],
  tracesSampleRate: 0.2,
  enabled: Boolean(import.meta.env.VITE_SENTRY_DSN),
})

O DSN do navegador é público por natureza: vai no JavaScript que qualquer pessoa baixa, e só permite enviar eventos. O que nunca pode aparecer no front é o token de autenticação da API do Sentry. E sem source map a pilha chega ilegível (t.e is not a function, linha 1): gere os mapas no build e envie-os com o plugin oficial do Sentry para Vite, e o painel passa a mostrar o seu código original.

⚠️ Atenção Não mande dado pessoal para o Sentry. sendDefaultPii: false é o padrão e deve continuar assim. Se usar Sentry.setUser, passe um identificador interno ({ id: usuario.id }), não o e-mail. E revise as mensagens da sua própria API: Usuário maria@exemplo.com não encontrado vira vazamento no momento em que essa string sobe para um serviço de terceiros.

7.2 Logs estruturados com pino¶

Usuário logou às 3 da tarde é ótimo para ler uma linha e péssimo para responder "quantos logins falharam na última hora?". Log estruturado resolve: cada linha é um JSON com campos fixos, e a busca vira filtro.

npm install pino pino-http && npm install --save-dev pino-pretty

unieventos-api/src/log.js

import pino from 'pino'

export const log = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  // Campos que nunca podem sair no log, por mais fundo que estejam no objeto.
  redact: {
    paths: ['req.headers.authorization', 'req.headers.cookie', '*.senha', '*.token'],
    censor: '[oculto]',
  },
  // Nome do serviço em toda linha: essencial quando dois processos escrevem no mesmo lugar.
  base: { servico: 'unieventos-api' },
})

Com o middleware registrado, o console.error do tratador de erro da §7.1 vira req.log.error({ err: erro }, 'erro não tratado') — a mesma linha, agora amarrada ao identificador da requisição. No src/app.js, app.use(pinoHttp({ logger: log })) antes de tudo gera uma linha por requisição, com método, rota, status e duração. Dentro de qualquer rota, req.log é um logger já preenchido com o identificador daquela requisição: req.log.info({ inscricaoId: inscricao.id }, 'inscrição criada') produz uma linha JSON com level, time, servico, reqId, inscricaoId e msg. Os níveis são numéricos: trace 10, debug 20, info 30, warn 40, error 50, fatal 60. Definir LOG_LEVEL=warn faz o pino descartar tudo abaixo de 40 sem nem formatar a mensagem — por isso ele é rápido o bastante para ficar ligado em produção.

node src/server.js | npx pino-pretty                              # legível no desenvolvimento
grep '"level":50' ~/.pm2/logs/unieventos-api-out.log | tail -20   # erros no servidor
tail -500 ~/.pm2/logs/unieventos-api-out.log | jq -c 'select(.level >= 40) | {msg, url: .req.url}'

7.3 Rotação: o log que enche o disco¶

Um arquivo de log cresce para sempre, e servidor de projeto pequeno para por disco cheio de log — o sintoma é bonito: tudo funciona, até que nada funciona. Com pm2 (Capítulo 06), o módulo oficial resolve; com o logrotate do sistema, que já roda diariamente no Ubuntu, é um arquivo de configuração:

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 14
pm2 set pm2-logrotate:compress true

/etc/logrotate.d/unieventos

/home/deploy/.pm2/logs/*.log {
    daily
    rotate 14
    maxsize 20M
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

copytruncate é a chave quando o processo mantém o arquivo aberto (o caso do pm2): o logrotate copia o conteúdo e zera o original, em vez de renomeá-lo e deixar o processo escrevendo em um arquivo invisível. Teste sem esperar um dia com sudo logrotate -d /etc/logrotate.d/unieventos (simula) e -f (força). Se a sua API roda como serviço systemd e escreve na saída padrão — o laboratório dsw-gN do Capítulo 06 —, o journald já faz a rotação (journalctl -u dsw-g3 -n 100 --no-pager).

8. Uptime, robots.txt e sitemap.xml¶

Um monitor de disponibilidade chama uma URL em intervalos fixos e avisa quando a resposta muda. Configuração mínima: alvo https://api.seudominio.dev/health (não a home do site — uma home estática continua respondendo 200 com a API caída); intervalo de 5 minutos, que é o do plano gratuito do UptimeRobot; condição de alerta status diferente de 200 ou corpo sem a palavra ok, o que pega o caso em que o processo responde mas o banco caiu; e pelo menos um canal que apite no celular. O UptimeRobot dá 50 monitores no plano gratuito; o Better Stack dá menos monitores, intervalo menor e uma página de status pública — detalhe profissional barato, que deixa qualquer pessoa descobrir se o problema é o sistema ou a internet dela.

Vale melhorar o /health para que ele signifique alguma coisa:

unieventos-api/src/rotas/saude.js

import { Router } from 'express'
import { pool } from '../db/pool.js'

const rotas = Router()

rotas.get('/health', async (req, res) => {
  try {
    // Uma consulta trivial prova que a conexão com o banco está viva.
    await pool.query('SELECT 1')
    res.json({ status: 'ok', versao: process.env.APP_VERSION ?? 'dev' })
  } catch (erro) {
    req.log.error({ err: erro }, 'health check falhou')
    res.status(503).json({ status: 'degradado', detalhe: 'banco indisponível' })
  }
})

export default rotas

O robots.txt fica na raiz do domínio e diz aos rastreadores o que podem visitar. Ele não protege nada — é um pedido, não uma tranca.

unieventos-web/public/robots.txt

User-agent: *
Allow: /
Disallow: /admin

Sitemap: https://eventos.seudominio.dev/sitemap.xml

Em um ambiente de teste ou homologação o arquivo é outro (User-agent: * seguido de Disallow: /) — esquecer disso é como um endereço de rascunho aparece no Google. O sitemap lista as URLs que você quer indexadas; em um site pequeno pode ser escrito à mão:

unieventos-web/public/sitemap.xml

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://eventos.seudominio.dev/</loc>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>
</urlset>

Se o seu site tem páginas geradas a partir do banco (uma por evento), escreva um script que gere o arquivo no build e inclua a tag <lastmod> com a data da última alteração de cada registro — assim o buscador sabe o que revisitar. Arquivo gerado por script não erra e não envelhece.

📌 Vale gravar Saber diferenciar as três métricas do Core Web Vitals pela pergunta que cada uma responde; saber que dado de laboratório (Lighthouse) e dado de campo (usuários reais) medem coisas diferentes; e explicar por que robots.txt não é mecanismo de segurança.

🚀 Passo a passo — UniEventos medido, testado e vigiado¶

Ao fim destes passos você tem: linter e formatador nos dois projetos, testes rodando local e no CI, um relatório Lighthouse antes e outro depois com a diferença explicada, erros de produção chegando ao seu e-mail e um monitor apitando se a API cair.

Está no Nível 2? Aplique o mesmo passo na cafe-cerrado-api e no front do Café Cerrado: o linter, os testes com Vitest e supertest, o Lighthouse e o Sentry não dependem do domínio do projeto — só das rotas que você tem.

Passo 1 — Linha de base (faça antes de mexer em qualquer coisa)¶

cd ~/weblab/unieventos-web
mkdir -p relatorios
npx lighthouse@latest https://eventos.seudominio.dev \
  --output=html --output=json --output-path=./relatorios/antes \
  --chrome-flags="--headless" --quiet

Anote em relatorios/comparativo.md: nota de Performance, LCP, CLS, TBT e total transferido. Sem esta medição, o resto do capítulo vira opinião.

Passo 2 — ESLint e Prettier nos dois projetos¶

Instale as dependências das §2.2 e §2.3, crie os dois eslint.config.js, o .prettierrc (Capítulo 01) e o .prettierignore. Em cada projeto:

npx eslint .
npx prettier --write .
npx eslint . --fix
npx eslint .

Esperado: a primeira execução lista problemas; a última não lista nenhum. Leia cada erro que o --fix não resolveu — quase sempre há uma variável não usada revelando código morto. Acrescente os scripts de qualidade aos dois package.json.

Passo 3 — Testes dos dois projetos¶

Na API, garanta vitest, supertest e @vitest/coverage-v8 instalados e crie tests/paginacao.test.js e tests/eventos.test.js (§3), adaptando os nomes de rota. No front, instale vitest, @vue/test-utils, jsdom e @vitest/coverage-v8 e crie vitest.config.js, vitest.setup.js e o teste de componente da §4.

cd ~/weblab/unieventos-api && npm test && npm run test:cobertura
cd ~/weblab/unieventos-web && npm run test:unit

Esperado: todos passam e a tabela de cobertura aparece. Se o processo da API travar sem terminar, o after não está fechando o servidor.

Passo 4 — As correções de performance¶

Aplique nesta ordem, rodando npm run build antes e depois do item 4:

1. Converta a imagem do topo para WebP, redimensione-a e adicione width, height e fetchpriority="high".
2. Ponha loading="lazy" nas imagens dos cards de evento.
3. Ajuste a fonte com preconnect e display=swap (ou baixe os .woff2).
4. Troque as rotas do Vue Router por importação dinâmica.
5. No servidor, aplique os blocos de cache e de gzip da §6 e recarregue o nginx.

sudo nginx -t && sudo systemctl reload nginx
curl -sI -H 'Accept-Encoding: gzip' https://eventos.seudominio.dev/ | grep -i -E 'content-encoding|cache-control'

Passo 5 — Publique e meça de novo¶

cd ~/weblab/unieventos-web
npm run build
rsync -avz --delete dist/ meuvps:/var/www/unieventos-web/
npx lighthouse@latest https://eventos.seudominio.dev \
  --output=html --output=json --output-path=./relatorios/depois \
  --chrome-flags="--headless" --quiet

Complete o comparativo.md com uma tabela antes/depois e uma frase por linha dizendo qual correção causou aquela mudança. É esse documento, não a nota, que prova que você entendeu.

Passo 6 — Sentry nos dois lados¶

Crie os dois projetos no Sentry. Na API: instrument.js, SENTRY_DSN no .env (e nas variáveis do Render ou do serviço systemd), start com --import e Sentry.setupExpressErrorHandler(app). No front: VITE_SENTRY_DSN e o Sentry.init da §7.1. Para conferir, crie uma rota /api/erro-de-teste que lança throw new Error('teste de instrumentação'), chame-a com curl, confirme que o evento aparece no painel em segundos e apague a rota em seguida.

Passo 7 — pino, rotação, CI e uptime¶

Instale pino e pino-http, crie src/log.js, registre o middleware e troque os console.log restantes por req.log ou log. No servidor, configure pm2-logrotate ou /etc/logrotate.d/unieventos. Crie o .github/workflows/qualidade.yml e o lighthouserc.json (§5.2), faça o push e confira a marca verde no pull request. Por fim, cadastre o monitor de /health no UptimeRobot com alerta por e-mail.

Como conferir¶

🧪 Laboratório¶

Nível A — Fixação¶

A1. No eslint.config.js da API, o objeto prettier está no fim do array. O que acontece se você movê-lo para antes de js.configs.recommended? Justifique com a regra de precedência do flat config.

A2. Classifique cada problema como "o linter pega", "o teste pega", "o Lighthouse pega" ou "só a observabilidade pega": (a) if (idade = 18) com um só sinal de igual; (b) a paginação devolve a página 0 com lista vazia; (c) a imagem do topo tem 2,4 MB; (d) a API devolve 500 apenas quando o usuário tem acento no nome.

A3. expect('3').toBe(3) passa ou falha no Vitest? E assert.equal('3', 3) com node:assert/strict e com o node:assert comum? Explique por que um comparador que coage tipos torna um teste perigoso.

A4. Uma página tem LCP de 1,8 s, INP de 90 ms e CLS de 0,32. Quais métricas estão na faixa boa e qual é o provável culpado do valor ruim?

A5. Explique em uma frase por que loading="lazy" na imagem do topo piora o LCP, enquanto a mesma propriedade nas imagens do rodapé melhora o carregamento.

A6. Os arquivos gerados pelo Vite têm hash no nome (index-B7fK2p.js). Como isso permite Cache-Control: public, immutable por um ano sem prender o usuário a uma versão antiga? E por que o index.html não pode receber o mesmo cabeçalho?

Nível B — Aplicação¶

B1. Cobertura dirigida. Rode npm run test:cobertura na sua API, escolha o arquivo com a menor cobertura de linhas e escreva três testes que subam esse número em pelo menos 20 pontos percentuais. Pelo menos um deve exercitar um caminho de erro (entrada inválida, recurso inexistente).

Resultado esperado: a tabela de cobertura antes e depois, colada no README.md, com a diferença destacada.

B2. Um linter que reprova de propósito. Introduza três problemas no seu código — uma variável declarada e não usada, um == em vez de === e um var — e comprove que npm run lint falha com código de saída diferente de zero (echo $?). Depois corrija dois com --fix e explique por que o terceiro exigiu decisão sua.

Resultado esperado: o log dos dois npm run lint (antes e depois) e um parágrafo dizendo qual problema o --fix não resolveu e por quê.

B3. Orçamento de performance. Adicione ao seu lighthouserc.json asserções que reprovem o build se a nota de performance cair abaixo de 0,9, a de acessibilidade abaixo de 0,95 ou o LCP passar de 2500 ms. Faça um commit que quebre uma delas de propósito (trocando a imagem do topo por uma versão gigante, por exemplo) e mostre o CI vermelho.

Resultado esperado: dois links de execução do workflow — um verde e um vermelho — e a mensagem exata da asserção que falhou.

Nível C — Desafio¶

C1. Bug plantado, teste primeiro. Peça a um colega que introduza um bug em uma função de regra de negócio da sua API, sem dizer qual. Sua missão, em ordem obrigatória: (1) descubra o bug pelo comportamento, não lendo o diff; (2) escreva um teste que falha por causa dele; (3) só então corrija; (4) confirme que o teste passa. Troque de papel e repita. No fim, os dois repositórios têm um teste novo cada, com uma mensagem de commit explicando o bug capturado.

🏆 Desafios¶

🐛 Erros comuns¶

🏠 Para praticar depois da aula (1 h)¶

No repositório do seu projeto autoral (front e API):

1. Configure ESLint 9 em flat config e Prettier nos dois projetos, com os scripts lint, formatar:conferir e qualidade. Rode npm run lint:corrigir, corrija o que sobrar e comite em um commit separado chamado chore: lint e formatação.
2. Escreva no mínimo quatro testes: dois de unidade sobre uma regra de negócio sua e dois de integração sobre a rota principal da API (um caminho feliz e um de erro).
3. Meça o site publicado com a CLI do Lighthouse, aplique duas correções de performance e meça de novo. Guarde os dois relatórios em relatorios/ e escreva o comparativo.md.
4. Configure o Sentry no front (é o mais rápido dos dois) e force um erro para confirmar que o evento chega.

Critério de pronto: npm run qualidade termina sem erro nos dois projetos; relatorios/comparativo.md mostra a nota antes e depois com as duas correções nomeadas; existe uma captura de tela do evento no painel do Sentry.

Guarde no seu repositório: commit + push, com o comparativo.md visível na raiz e a captura em relatorios/.

✅ Está no ar quando…¶

• [ ] npm run lint e npm run formatar:conferir passam nos dois projetos, sem avisos (--max-warnings=0).
• [ ] npm test na API roda pelo menos um teste de unidade e um de integração, e o processo encerra sozinho.
• [ ] O workflow de qualidade roda em cada pull request e a branch main exige que ele passe.
• [ ] Existem dois relatórios do Lighthouse no repositório e um comparativo.md explicando a diferença.
• [ ] Performance e Accessibility do site publicado estão em 90 ou mais no modo Mobile.
• [ ] curl -sI mostra content-encoding: gzip nos arquivos de texto e cache-control: public, immutable nos arquivos com hash.
• [ ] Um erro proposital na API aparece no painel do Sentry em menos de um minuto, com pilha legível.
• [ ] Uma linha de log da API é JSON válido, tem servico e level, e não contém token nem senha.
• [ ] Um monitor de uptime vigia /health e você recebeu ao menos um alerta de teste.
• [ ] https://eventos.seudominio.dev/robots.txt e /sitemap.xml respondem 200 com o conteúdo correto para produção.

📚 Para aprofundar¶

• ESLint — Configuration Files — o flat config item a item, com a ordem de precedência.
• eslint-plugin-vue — os presets flat/essential e flat/recommended e o que cada regra verifica.
• Prettier — Integrating with Linters — por que o eslint-config-prettier existe e como configurá-lo.
• Node.js — Test runner — a API completa de node:test, o executor embutido: a alternativa sem dependências citada na §3.1.
• Vitest — Getting Started — configuração, modo de observação e cobertura.
• Vue Test Utils — mount, props, emitted, trigger e testes assíncronos de componente.
• web.dev — Core Web Vitals — definição, limites e a diferença entre dado de campo e de laboratório.
• Lighthouse — documentação — categorias, cálculo da nota e uso da CLI.
• Lighthouse CI — lhci autorun, asserções e orçamento de performance.
• Sentry — Node.js e Sentry — Vue — instalação, instrument.js, integrações e source maps.
• pino — documentação — níveis, redact, transportes e o pino-http para Express.
• nginx — módulo gzip e módulo headers — diretivas gzip*, expires e add_header.
• MDN — atributo loading — quando o carregamento adiado ajuda e quando atrapalha.
• sitemaps.org e Google Search Central — robots.txt — o formato dos dois arquivos, direto da fonte.

No próximo capítulo a trilha fecha com a ferramenta mais nova e mais mal usada da caixa: assistentes de inteligência artificial. Você vai aprender a dar contexto em um prompt, a desconfiar de API inventada, a usar a IA para revisar o seu projeto autoral — e a regra que vale nos três Níveis do WebLab sobre o que é apoio e o que é cola.