2026-1 MeasureSoftGram Frontend

July 11, 2026 · View on GitHub

Frontend repository of MeasureSoftGram application in 2026.1.

Badges

🚧 Work in Progress 🚧

Requirements

Local development (without Docker)

  • Node.js 20.x
  • corepack enabled
  • pnpm 9.0.0 (pin unico em package.json packageManager e no Dockerfile)

Development with Docker

  • Docker
  • Docker Compose v.2

Environment configuration

Create the .env file at the root of the project:

cp .env.example .env

Make sure to set the URL for your backend API.

O compose do Front sobe somente o serviço front. Backend (Service + Postgres) é responsabilidade do compose do repositório 2026.1-MeasureSoftGram-Service — suba lá primeiro.

1) Subir o Service (em outro terminal, no repo do Service)

cd ../2026.1-MeasureSoftGram-Service
cp -R env-vars-example env-vars   # primeiro setup
docker compose up -d

API disponível em http://localhost:8080.

2) Subir o Front

docker compose up --build

Aplicação disponível em http://localhost:3000.

No container do Front, SERVICE_URL aponta para http://host.docker.internal:8080 para acessar o Service rodando no host. No browser, NEXT_PUBLIC_API_URL segue como http://localhost:8080.

3) Parar containers

docker compose down

4) Scripts Úteis

  • Rodar linter:
make lint
  • Rodar testes:
make test
  • Rodar testes no modo CI:
make ci-test
  • Build de Produção
make build
make start
  • Comandos personalizados
make pnpm SCRIPT=<script> [ARGS="..."]

permite executar qualquer script do package.json dentro do container, passando argumentos adicionais se desejado.

Exemplo:

make pnpm SCRIPT=build

ou

make pnpm SCRIPT=test ARGS="src/pages"

Rodar localmente (sem Docker)

Primeiramente garanta que está utilizando a versão 20 do Node. Ferramentas para gerenciamento de versões Node como nvm e n podem ser úteis.

1) Ativar pnpm

corepack enable
corepack prepare pnpm@9.0.0 --activate
pnpm -v

2) Instalar dependências

pnpm install

Atalho: make setup faz os passos 1 e 2 de uma vez (ativa o pnpm via corepack, instala as dependências com --frozen-lockfile e cria o .env a partir do .env.example).

3) Subir o projeto

pnpm dev

Aplicação disponível em: http://localhost:3000

4) Scripts úteis

  • Rodar linter:
pnpm lint
  • Rodar testes (watch, so o que mudou - uso local):
pnpm test
  • Rodar a suite completa deterministica (mesmo modo do CI, sem reescrever snapshot):
pnpm test:all
  • Checar tipos (tsc --noEmit):
pnpm typecheck

Nota sobre o typecheck: hoje o tsc --noEmit acusa erros de parse nos type defs da react-i18next 15.x, que o TypeScript 4.7.4 (pin do projeto) nao consegue ler; nao sao erros do codigo do projeto. Por isso o typecheck ainda nao e gate bloqueante no CI. Subir o TypeScript pra destravar isso esta rastreado numa issue de follow-up.

  • Build de produção:
pnpm build
pnpm start

Rodar sem backend (modo mock)

Precisa navegar pelas telas autenticadas sem subir Django nem Postgres? Use o modo mock, que intercepta as chamadas HTTP com o MSW e responde com fixtures versionadas em src/mocks/.

pnpm dev:mock

Aplicação disponível em http://localhost:3000 já autenticada (o modo mock semeia uma sessão fake no localStorage), sem nenhum backend no ar.

Detalhes:

  • Ativado pela variável NEXT_PUBLIC_API_MOCKING=enabled (o script dev:mock já a define, junto de um NEXT_PUBLIC_API_URL de exemplo). Sem essa variável o código de mock fica inerte: pnpm dev, pnpm build e pnpm test:all seguem batendo no backend real, sem qualquer interferência.
  • Os handlers ficam em src/mocks/handlers.ts e as fixtures em src/mocks/fixtures/. Para cobrir uma tela nova, adicione o endpoint correspondente ali.
  • O worker do service worker é o arquivo versionado public/mockServiceWorker.js (gerado por npx msw init public/); não edite à mão.

Rodar com Docker (stack completa)

Para subir o Front junto com o Service (imagem publicada) e o Postgres num comando só, use o docker-compose-dev.yml. Há atalhos no Makefile:

make dev     # sobe front + Service + Postgres em foreground (com logs)
make up      # o mesmo, em background (-d)
make down    # derruba a stack
  • Front em http://localhost:3000, Service em http://localhost:8080.
  • As credenciais do Service/Postgres ficam em env-vars/.service.env e env-vars/.postgres.env (já versionados com defaults de dev).
  • Para o login com GitHub funcionar, ajuste GITHUB_CLIENT_ID/GITHUB_SECRET (ver README do Service).

Troubleshooting

Erro de versão do Node com pnpm

Se aparecer algo como: This version of pnpm requires at least Node.js v18.12

Garanta que você está usando Node 20:

node -v
v20.20.2

Erro de permissão no .next (EACCES)

Se aparecer erro ao rodar pnpm dev:

sudo chown -R $USER:$USER .next node_modules .pnpm-store
chmod -R u+rwX .next
rm -rf .next
pnpm dev

Evite rodar comandos de node/pnpm com sudo dentro do projeto.

Governança e contribuição

  • Licença: este projeto é distribuído sob a GNU AGPL-3.0.
  • Código de conduta: consulte CODE_OF_CONDUCT.md antes de interagir com a comunidade.
  • Como contribuir: veja CONTRIBUTING.md para padrões de branch, PR e revisão.