Esta ferramenta permite criar e personalizar rapidamente elementos estatísticos e visuais para o teu GitHub Profile README.
Foi desenvolvida especialmente para ajudar programadores iniciantes, estudantes ou qualquer pessoa que deseje um perfil mais organizado, limpo e profissional, mas que:
- Ainda está a começar no GitHub;
- Tem dificuldade em interpretar documentações técnicas em inglês;
- Prefere evitar escrever código manualmente para obter um resultado visual de qualidade.
O objectivo principal é simplificar o processo de embelezamento do README, permitindo que qualquer utilizador consiga um perfil com aparência profissional em poucos minutos.
Mostra a sequência (streak) de contribuições diárias consecutivas no GitHub. Este elemento visual incentiva a consistência, ajuda a manter a disciplina e oferece uma motivação imediata ao ser exibido directamente no README do perfil público.
Exemplo de Streak Stats
Apresenta um cartão com estatísticas gerais da conta GitHub, incluindo:
- Número total de commits;
- Número de repositórios públicos e privados;
- Pull requests;
- Issues;
- Linguagens mais utilizadas;
- Entre outras métricas relevantes.
Facilita uma visão rápida e clara da actividade do utilizador no perfil público.
Exemplo Github Stats
Exemplo WakaTime Stats
Permite escolher e fixar (pin) repositórios importantes no topo do README, mesmo que não sejam os mais populares ou recentes. É útil para destacar projectos prioritários, portfólio pessoal, trabalhos académicos ou contribuições que desejas que sejam vistas imediatamente.
Exemplo Repositório Extra Pin
Exemplo Gist Pin
Exemplo Top Linguagens
Gera badges (escudos) personalizáveis que comunicam informação de forma visual e atractiva. Podem representar:
- Tecnologias e linguagens que dominas;
- Ferramentas e plataformas que utilizas;
- Estados de projectos (em desenvolvimento, estável, abandonado, etc.);
- Métricas diversas (downloads, versão, licença, etc.).
Aumentam significativamente a credibilidade visual e a profissionalização do perfil.
Exemplo de Badges sem Logotipo
Exemplo de Badges com Logotipo
Exemplo de Badges com Logotipo e Interativo (Link)
Exemplo de Badges de Visualizações de Perfil
-
Abre o terminal no teu sistema operativo.
-
Executa os comandos na seguinte ordem:
# 1. Clona o repositório
git clone https://github.com/heliocarlitos/nice-readme.git
# 2. Entra na directoria do projecto
cd nice-readme
# 3. Instala as dependências
npm installnpm run devApós executar este comando, o projecto fica disponível em:
-
É necessário ter o Node.js instalado (versão 20 ou superior recomendada).
Verifica a versão instalada com o comando:node -v
-
O projecto utiliza Next.js 16 + React 19 — combinação recente.
As versões mais compatíveis e recomendadas do Node.js são: 20.x ou 22.x. -
Caso ocorram erros durante a instalação das dependências (
npm install), experimenta uma das seguintes soluções:# Solução 1 – ignora conflitos de peer dependencies npm install --legacy-peer-deps# Solução 2 – limpeza completa e reinstalação rm -rf node_modules package-lock.json npm install
- Acede a: https://console.firebase.google.com
- Clica em Adicionar projecto ou Criar um projecto
- Define um nome para o projecto (exemplo:
nice-readme-app) - Decide se queres activar o Google Analytics (podes desactivar não é necesário)
- Clica em Criar projecto → Continuar
- No menu lateral esquerdo, selecciona Firestore Database (ou Cloud Firestore)
- Clica no botão Criar base de dados
- Escolhe Iniciar no modo de produção
- Selecciona a localização da base de dados
(escolhe uma região próxima de ti ou dos teus utilizadores, ex.:europe-west)
Atenção: esta escolha é definitiva e não pode ser alterada posteriormente - Clica em Activar
- Ainda dentro de Firestore Database, clica no separador Regras
- Apaga todo o conteúdo existente
- Cola exactamente o seguinte código:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /tool_usage/{doc} {
allow read, create, delete: if true;
allow update: if false;
}
match /admin/{doc} {
allow read: if true;
allow write: if false;
}
}
}- Clica em Publicar
Significado destas regras:
- Na colecção
tool_usage: qualquer pessoa pode ler e criar registos, mas ninguém pode alterar ou apagar registos já existentes (imutabilidade intencional) - Na colecção
admin: apenas leitura é permitida (usada para autenticação simples da área administrativa)
- No separador Dados do Firestore
- Clica em Iniciar colecção (ou + Iniciar colecção)
- No campo ID da colecção escreve exactamente:
admin - Clica em Seguinte
- Cria um documento com ID automático
- Adiciona os dois campos seguintes:
| Nome do campo | Tipo | Valor / Observação |
|---|---|---|
| user | string | O teu nome de utilizador (recomenda-se o mesmo do GitHub) |
| password | string | Uma palavra-passe forte da tua escolha (guarda em segurança) |
- Clica em Guardar
Warning
Estas credenciais são as únicas que permitem aceder à página /admin. Guarda-as em local seguro e nunca as publiques em repositórios, ficheiros versionados ou mensagens.
- Clica no ícone de engrenagem (canto superior esquerdo) → Definições do projecto
- Desce até à secção Os teus apps
- Se ainda não existe uma app web, clica no ícone </> (Web)
- Dá um nome à aplicação (exemplo:
nice-readme-web) - Não marques a opção de configurar o Firebase Hosting
- Clica em Registar app
- Copia o objecto
firebaseConfigapresentado
Warning
Estes valores contêm chaves sensíveis. Nunca os partilhes publicamente.
Cria (ou edita) o ficheiro .env.local na raiz do projecto e adiciona:
NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=nome-do-projeto.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=nome-do-projeto
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=nome-do-projeto.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789012
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789012:web:abcdef1234567890abcdefNote
Todas as variáveis expostas ao cliente devem começar por NEXT_PUBLIC_
Guarda o ficheiro e reinicia o servidor (npm run dev).
- Acede ao teu projecto no painel do Vercel
- Vai a Settings → Environment Variables
- Adiciona cada variável individualmente (nome e valor exactamente como no
.env.local) - Após adicionar todas as 6 variáveis, realiza um Redeploy (clica nos três pontos no último deploy → Redeploy) ou faz um novo push para o repositório
Com esta configuração concluída, o projecto consegue comunicar com o Firebase e registar utilizações na colecção tool_usage.
Dúvidas ou problemas? Podes abrir uma issue aqui.
Embora o site https://nice-readme.vercel.app tenham sido desenvolvidos por mim, as funcionalidades principais dependem de bibliotecas e serviços open-source criados por outras pessoas e equipas. Todo o mérito técnico pelas estatísticas, badges e contadores vai para os seguintes projectos e autores:
 Anurag Hazra github-readme-stats |
 Shields.io Badges / Shields |
 Jonah Lawrence github-readme-streak-stats |
 Anton Komarev Profile Views Counter |
O projecto Nice Readme está licenciado sob a Licença MIT. Podes consultar o ficheiro completo da licença aqui.