Hevy Insights

This project is a used to gather data from Hevy API endpoints and visualize it in a web interface, acting as alternative for the Hevy PRO membership.

Note

Check it out at: Hevy Insights Online

About Hevy Insights

Hevy Insights is a dynamic web application that provides insights and analytics of your workouts and exercises. It visualizes workout data from the Hevy app in a clean dashboard so that you can always keep track of your progress!

In the Hevy app you can only see your stats and progress up to 3 months for free, otherwise you need the paid Hevy PRO membership. Hevy Insights allows you to log in with your Hevy credentials and fetch your workout data directly from Hevy's API, providing you with detailed visualizations and historical data up to the date of your account creation - no PRO membership required!

Features

Authentication: Multiple login options for flexibility:
- Hevy Credentials: Login with your Hevy username/email and password (no PRO membership required)
- Hevy PRO API Key: Use your revokable Hevy PRO API key from hevy.com/settings?developer
- CSV Upload: Upload your exported workout CSV file from the Hevy app
- All credentials are stored in your browser's local storage only
Dashboard: Interactive charts and statistics of your workouts, including volume, muscle distribution and hours trained.
Workout History: Workout logs with detailed exercise information up to the date of account creation - card or list design.
Exercises: View all exercises with video thumbnails and detailed stats.
- Plateau Detection: Automatically detects when your performance has plateaued on an exercise
- Strength Tracking: Shows if you're gaining or losing strength over your recent sessions
Custom Settings: Individualize your experience when using Hevy Insights.
Languages: Language support for 🇺🇸, 🇩🇪 and 🇪🇸.

Plateau & Strength Detection

Hevy Insights includes an intelligent analysis system that tracks your performance across the last 5 sessions for each exercise and provides real-time feedback:

Detection Types

🟡 Plateau: Your performance has stayed relatively consistent
- Triggered when weight stays within ~0.5kg and reps within ~1 rep across at least 5 sessions
🟢 Gaining Strength: You're making progress!
- Triggered when weight increases by >2kg OR reps increase by >2 (with stable/increasing weight) across at least 5 sessions
🔴 Declining Strength: Performance is decreasing
- Triggered when weight decreases by >2kg OR reps decrease by >2 (with stable/ decreasing weight) across at least 5 sessions
⚪ Insufficient Data: Not enough workout history yet
- Displayed when an exercise has been performed fewer than 5 times

How It Works

The analysis algorithm:

Collects data from your last 5 workout sessions for each exercise
Tracks the maximum weight and reps at max weight for each session
Compares the first half of sessions against the second half to identify trends
Displays a colored badge on each exercise card with the current status

This feature helps you identify when it's time to:

Increase weight (when plateaued)
Celebrate progress (when gaining)
Take recovery time or check form (when declining)
Build more history (when insufficient data)

Screenshots

Note

Screenshots as of v1.3.0

Login Page

Dashboard

Workouts Page - Card Design

Workouts Page - List Design

Login Comparison

You can decide based on your needs which login method suits you best:

Tip

I recommed using the Hevy Credentials Login for the best experience since it shows the most data.

Feature	Hevy Credentials Login	Hevy PRO API Key Login	CSV Upload
Requires Hevy PRO Membership	✅ No	❌ Yes	✅ No
Data Freshness	✅ Live data from Hevy API	✅ Live data from Hevy API	❌ Static data from CSV file
Data Range	✅ Full history from Hevy API	✅ Full history from Hevy API	✅ Full history from CSV file
Personal Record Tracking	✅ Yes	❌ No	⚠️ Yes, but not in detail
Muscle Distribution Data	✅ Yes	❌ No	⚠️ Not everything
Media (Images/GIFs)	✅ Yes	❌ No	❌ No
Plateu Detection	✅ Yes	✅ Yes	✅ Yes
Workout Streaks	✅ Yes	✅ Yes	❌ No
Calories & Heart Rate Data	✅ Yes	❌ No	❌ No

Usage

You can either use Hevy Insights online or run it locally on your machine via multiple methods.

Hosted Online

Navigate to the hosted version of Hevy Insights at: https://hevy.kida.one

The latest version is always hosted there.

Important

Only your Hevy API token is stored at your own browser's local storage. No other data is stored!

Local Setup

Clone/download the repository and follow these steps:

Rename .env.example to .env.
Install the backend and frontend dependencies.
Start the backend (Terminal 1):

python backend/fastapi_server.py
Start the frontend (Terminal 2):

cd frontend; npm run dev
Open your browser and navigate to http://localhost:5173
Login with your Hevy username/email and password

Docker

Run the containers:

docker-compose up -d

Note

You can find the docker-compose.yaml file in the repository root folder.

Open your browser and navigate to http://localhost:8123
Login with your Hevy username/email and password or upload your exported CSV file

Future Goals

Better logging
Replace localStorage with HTTP cookie
Handle exercises with time (planks, jogging)
Move contribution graph to Dashboard
Add a better visual line between months in the contribution graph
Add visual representation of trained muscle groups (body heatmap)
Add i18n variables to pagination localization (specifically footer)
Add calendar filter
In-depth muscle analysis page
Remove emojis, use icons instead
Resort/group CSS styles better
Dashboard: Top stats: Display them more in rows instead of big "buttons". Maybe like "🏋️ 25 Total Workouts * 💪 282.741,5 kg Total Volume * ⏱️ 34h 15m Total Time Trained"
PRs on Dashboard: Showing hardcoded english "title" of exercise, not localized
CSV upload: PRs not shown and muscle regions missing
Contribution Graph: Fix timeline (still shows 2025 + 2026 data). Only show current year.
Enable/configure settings for date format, time format, week start day

Technical Documentation

Note

As of 19.12.2025, v1.3.0

Project Structure

hevy-insights/
├── backend/                   # Backend Components
│   ├── fastapi_server.py      # FastAPI server with REST endpoints
│   ├── hevy_api.py            # Hevy API module
│   └── requirements.txt       # Python backend dependencies
└── frontend/                  # Frontend Components
    ├── public/                # Static assets
    ├── src/                   # Vue 3 TypeScript application
    │   ├── locales/          # i18n language files
    │   ├── router/            # Vue Router configuration with auth guards
    │   │   └── index.ts       # Router entry point
    │   ├── services/          # API communication layer (Axios)
    │   │   └── api.ts         # Axios instance and API functions
    │   ├── stores/            # Pinia store for state management
    │   │   └── hevy_cache.ts  # Hevy data caching
    │   ├── utils/             # Utility functions
    │   │   ├── csvCalculator.ts  # CSV data calculation 
    │   │   └── csvParser.ts   # CSV data parsing
    │   ├── views/             # Page components (Login, Dashboard, Workouts, ...)
    │   ├── App.vue            # Root Vue component
    │   ├── main.ts            # Vue app entry point
    │   └── style.css          # Global styles
    ├── index.html             # HTML entry point
    ├── nginx.conf             # Nginx configuration for production
    ├── package-lock.json      # npm package lock file
    ├── package.json           # Node.js dependencies
    ├── tsconfig.app.json      # TypeScript configuration for the app
    ├── tsconfig.json          # TypeScript configuration
    ├── tsconfig.node.json     # TypeScript configuration for Node.js
    └── vite.config.ts         # Vite build configuration

High-Level-Flow

index.html: Browser loads this HTML document first. It defines the root node <div id="app"></div> and includes <script type="module" src="/src/main.ts">.
main.ts: Entry script runs. Vite serves ES modules and applies HMR in dev. We createApp(App), install Pinia and the Router, then mount("#app").
App.vue: Root component renders the global shell (fixed sidebar + main). On mount and after each route change it checks localStorage for hevy_auth_token to toggle sidebar visibility and protect routes.
Router: Resolves the current URL (/login, /dashboard, /workouts-card, /workouts-list) and renders the matched view inside <router-view />. Auth guards prevent accessing protected routes without a token.
View Components: The matched page component (Login.vue, Dashboard.vue, Workouts_Card.vue, .....vue) runs setup() and lifecycle hooks (onMounted).
Pinia Store (frontend/src/stores/hevy_cache.ts): Centralized state with 5‑minute caching for workouts (workoutsLastFetched). Exposes actions fetchUserAccount(), fetchWorkouts(force) and getters like username, hasWorkouts. Prevents redundant API calls when navigating.
Axios Service (frontend/src/services/api.ts): Configures base URL and injects the auth-token header via interceptors. All frontend API calls to the backend go through these typed helpers.
Backend (FastAPI): Serves /api endpoints. Validates auth-token and proxies requests to the official Hevy API. Frontend receives JSON responses and Vue reactivity updates the UI.

API Authentication Flow

User logs in via /api/login endpoint with Hevy credentials
Backend receives auth_token from Hevy API
Frontend stores token in localStorage
Subsequent API requests include token in auth-token header
Backend uses token to authenticate requests to Hevy API

API in Dev vs Prod

In development, the frontend talks directly to the FastAPI server: the Axios base URL in frontend/src/services/api.ts is http://localhost:5000/api when import.meta.env.PROD is false.
In production, the Axios base URL is /api (same origin). Requests resolve as https://your-domain/api/... and are reverse‑proxied to the backend by Nginx.
The import.meta.env.PROD flag is set automatically by Vite at build time. No extra configuration is required.

When nginx.conf is used

The file frontend/nginx.conf is used when the built frontend is served by Nginx (e.g. on a server with Nginx).
It performs two critical roles:
- SPA fallback: routes like /dashboard and /workouts-list return index.html so client‑side routing works.
- API proxy: requests to /api/... are forwarded to the FastAPI backend (e.g., http://backend:5000). This keeps a single public origin and avoids CORS in production.
If your deployment does not use Nginx (e.g., serving static files from a CDN without proxying), ensure your hosting platform supports SPA fallback and adjust the API base accordingly.

Direct-to-Backend with CORS

In local development, the frontend dev server runs on http://localhost:5173 and the backend on http://localhost:5000. Because these are different origins, FastAPI enables CORS middleware so the browser can call the backend directly.
CORS setup in fastapi_server.py.
In production behind Nginx, CORS is not required because the frontend and /api share the same origin.

Legal Disclaimer

This project is not affiliated with or endorsed by Hevy or its parent company. It is a third-party application developed for personal use and educational purposes only. Users are responsible for complying with Hevy's terms of service when using this application. The developer assumes no liability for any issues arising from the use of this software.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

I work on this project in my free time and unpaid. If you find it useful and would like to support its development, consider buying me a coffee:

Name		Name	Last commit message	Last commit date
Latest commit History 228 Commits
backend		backend
docs		docs
frontend		frontend
readme_images		readme_images
.env.example		.env.example
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yaml		docker-compose.yaml
ruff.toml		ruff.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Hevy Insights

About Hevy Insights

Table of Contents

Features