GitHub Fish Tank

Table of Contents

• 🚀 Project Overview
• ✨ Features
• 💻 Technologies
• 📋 Requirements
• 🛠️ Setup Instructions
• 📖 Usage
• 🐟 Fish List
• 📸 Screenshots

Project Overview

GitHub Fish Tank is a web application that transforms your GitHub language statistics into a living, animated aquarium. Each programming language becomes a uniquely shaped and colored fish swimming through a customizable underwater scene. It generates an SVG image that you can embed directly in your GitHub README profile.

Important

The public instance at https://gh-fish-tank.vercel.app can be unreliable due to GitHub API rate limits. Self-hosting (Vercel or other) or using the GitHub Actions workflow to generate aquarium in your profile repository is recommended.

Tip

You can download the generated SVG file and add it directly to your repository. This way, your fish tank will work completely offline without depending on the generation service.

Note

The application is available in English language version!

Features

• 🐠 38 Custom-designed fish models for specific programming languages
• 📊 Fish size is proportional to the percentage share of each language
• 🎨 Customizable aquarium appearance and decorations
• 🏷️ Optional legend and labels displayed on each fish
• 🔗 README-Ready URL generation
• 🚫 Language filtering – hide specific languages from the visualization
• 🖼️ Playful neobrutalist visual style
• 📱 Full responsiveness

Technologies

Backend

• Node.js
• Express
• GitHub REST API
• Vercel Functions

Frontend

• HTML
• CSS
• JavaScript

Requirements

Software versions used for development:

• npm 11.6.4
• Node.js 22.14.0
• Express 4.22.1

Warning

Compatibility with earlier versions has not been tested.

Setup Instructions

Just go to gh-fish-tank.vercel.app.

OR

To run a project locally, you must have Node.js and npm installed.

Important

Download guide: Installing Node.js and npm

You will also need a GitHub Personal Access Token (optional, but recommended to avoid rate limiting).

1. Download and extract the project folder.
2. Navigate to the project folder in your terminal.
3. Install dependencies:

$ npm install

4. (Optional) Add .env file in the root directory:

GITHUB_TOKEN=your_github_personal_access_token_here

5. Launch the development server:

npm run dev

6. Access the application at http://localhost:3000.

Usage

Just copy and paste this into your markdown - and you're done!

[![GitHub Fish Tank](https://gh-fish-tank.vercel.app/api/generate?user=hadoyyo&bg=4ecdc4&frame=3a4a5a&sand=c4a574&show_legend=true&show_language_labels=true&show_bubbles=true&show_rocks=true&show_plants=true&show_plants_alt=false&show_castle=true&show_ship=false&show_chest=true&show_shell=true&show_frame=false&show_anubias=false&show_statue=false&hide=php%2Cc)](https://github.com/hadoyyo)

Important

Remember to change username to your own!

Customize every detail of your fish tank - from the background to decorations - with simple URL parameters.

Name	Description	Type	Default value
user	GitHub username for the languages.	string	required
bg	Background color of the fish tank.	string (hex color)	#4ecdc4
frame	Color of the tank's frame.	string (hex color)	#3a4a5a
sand	Color of the sand at the bottom.	string (hex color)	#c4a574
show_legend	Displays the legend explaining fish (languages and percentage).	boolean	true
show_language_labels	Shows labels for programming languages (under the fish).	boolean	true
show_bubbles	Toggles the bubble animation.	boolean	true
show_rocks	Shows rocks decoration.	boolean	true
show_plants	Shows standard plants. Cannot be displayed together with show_plants_alt.	boolean	true
show_plants_alt	Shows alternative plants. Cannot be displayed together with show_plants.	boolean	false
show_castle	Shows a castle decoration. Cannot be displayed together with show_ship.	boolean	true
show_ship	Shows a sunken ship decoration. Cannot be displayed together with show_castle.	boolean	false
show_chest	Shows a treasure chest decoration. Cannot be displayed together with show_anubias.	boolean	true
show_anubias	Shows anubias plant. Cannot be displayed together with show_chest.	boolean	false
show_shell	Shows shell decoration. Cannot be displayed together with show_statue.	boolean	true
show_statue	Shows a statue decoration. Cannot be displayed together with show_shell.	boolean	false
show_frame	Toggles the visibility of the tank's frame.	boolean	true
hide	Comma-separated list of programming languages to hide from the tank (URL-encoded). Example: hide=php%2Cc hides PHP and C.	string (comma-separated)	none

Tip

The following pairs are mutually exclusive. If both are set to true, only the first (default) one will be displayed:

• show_plants / show_plants_alt → defaults to show_plants
• show_castle / show_ship → defaults to show_castle
• show_chest / show_anubias → defaults to show_chest
• show_shell / show_statue → defaults to show_shell

Examples

Standard Tank

Moon Tank with yellow frame

Blackwater River

Deep Sea Tank

Fish List

The main color of the fish correspond to the color assigned to each language on GitHub.

List of languages that have a unique fish model:

Language	Preview	Language	Preview	Language	Preview
JavaScript		TypeScript		Python
Java		C++		C#
Go		Rust		Ruby
PHP		Swift		Kotlin
HTML		CSS		Shell
Vue		Dart		Scala
Haskell		Elixir		Clojure
Lua		R		Dockerfile
Perl		MATLAB		Erlang
Julia		Jupyter N.		Vim
C		TeX		Nix
Assembly		Svelte		Solidity
Zig		Fortran

Other languages will use one of the following models:

Screenshots

Mobile Device