Building fitness applications requires accurate, reliable calculations. Whether you're developing a gym management platform, a personal training app, or a health tracking tool, getting the math right for BMI, calorie expenditure, one-rep max estimations, and macro breakdowns is critical — and surprisingly time-consuming to implement from scratch.
That's why we built @finegym/fitness-calc, a comprehensive open-source TypeScript library that handles all the fitness math so you don't have to. It's free, zero-dependency, and available on npm and GitHub.
This article walks through why we created this library, what it includes, and how developers and fitness businesses can use it to build better products faster. For broader context on how technology is reshaping the fitness industry, explore our analysis of fitness technology trends shaping the industry.
Why We Built an Open-Source Fitness Calculator
At FineGym, we build gym management software that helps fitness businesses streamline their operations. During development, we needed reliable fitness calculations for features like member body composition tracking, workout planning tools, and nutrition guidance.
When we looked at existing npm packages, we found:
- Incomplete coverage — most libraries only handle BMI and BMR, ignoring strength training formulas, heart rate zones, and pace calculations
- Abandoned projects — the top packages hadn't been updated in over a year, with zero maintenance
- No TypeScript support — poor or missing type definitions made integration painful
- Single-formula limitations — most 1RM calculators only implement one formula instead of giving developers options
Rather than cobbling together five different unmaintained packages, we built one comprehensive library and decided to open-source it. The fitness developer community deserves better tools, and sharing this library aligns with our mission to advance fitness technology for everyone.
What's Inside the Library
The library covers 12 calculation categories with over 40 functions, all backed by peer-reviewed scientific formulas. Here's a breakdown of what's available.
Body Mass Index (BMI)
Calculate BMI with WHO classification and healthy weight ranges. Supports both metric and imperial units.
import { calculateBMI } from '@finegym/fitness-calc';
const result = calculateBMI(75, 180);
// { bmi: 23.1, category: 'normal', healthyWeightRange: { min: 59.9, max: 80.7 } }
The library classifies BMI into 8 WHO categories: severe underweight through class 3 obesity. The healthyWeightRange field tells users exactly what weight range is considered normal for their height — useful for goal-setting interfaces in fitness apps.
Basal Metabolic Rate (BMR)
Three scientifically validated formulas for calculating resting energy expenditure:
- Mifflin-St Jeor (1990) — considered the most accurate for the general population
- Harris-Benedict (1919, revised 1984) — the classic formula still widely used in clinical settings
- Katch-McArdle — uses lean body mass for more accurate results when body fat percentage is known
import { calculateBMR } from '@finegym/fitness-calc';
const result = calculateBMR(80, 180, 30, 'male', 'mifflin_st_jeor');
// { bmr: 1780, formula: 'mifflin_st_jeor' }
Having multiple formulas lets developers offer comparison views or select the most appropriate formula based on available user data. If a member has had a body composition assessment, Katch-McArdle provides superior accuracy. For general use, Mifflin-St Jeor is the recommended default.
Total Daily Energy Expenditure (TDEE)
Combines BMR with activity level multipliers across six levels from sedentary to extra active.
import { calculateTDEE } from '@finegym/fitness-calc';
const result = calculateTDEE(80, 180, 30, 'male', 'moderate');
// { tdee: 2759, bmr: 1780, activityLevel: 'moderate' }
Activity levels follow the standard physical activity level (PAL) classifications used in nutritional science: sedentary (1.2), light (1.375), moderate (1.55), active (1.725), very active (1.9), and extra active (2.1). This is the foundation for any calorie-based feature in fitness applications.
Macronutrient Calculations
Six preset diet profiles plus support for custom ratios. Returns maintenance, cutting (-20%), and bulking (+15%) targets.
import { calculateMacros } from '@finegym/fitness-calc';
// Using a preset
const keto = calculateMacros(80, 180, 30, 'male', 'moderate', 'keto');
// Using custom ratios
const custom = calculateMacros(80, 180, 30, 'male', 'moderate', {
protein: 0.35, carbs: 0.40, fat: 0.25
});
Built-in presets include: balanced, low carb, high carb, high protein, keto, and zone diet. Each preset defines protein, carb, and fat ratios that sum to 1.0. The library converts calorie allocations to grams using standard conversion factors (4 cal/g for protein and carbs, 9 cal/g for fat).
For gym owners implementing nutrition software for personal trainers, these calculations provide the foundation for meal planning features.
One Rep Max (1RM) — 7 Formulas
This is where the library stands out from existing options. Seven validated formulas for estimating maximum strength:
- Epley — the most commonly used general-purpose formula
- Brzycki — popular in powerlifting communities, accurate for lower rep ranges
- Lombardi — uses a power function approach
- Mayhew et al. — exponential model validated across multiple studies
- O'Conner et al. — simple linear model
- Wathan — performs well for higher rep ranges
- Lander — linear model with different coefficients
import { calculateOneRepMax, calculateAllFormulas } from '@finegym/fitness-calc';
// Single formula
const result = calculateOneRepMax(100, 5, 'brzycki');
// { oneRepMax: 112.5, formula: 'brzycki', percentages: { 100: 112.5, 95: 106.9, ... } }
// Compare all formulas at once
const all = calculateAllFormulas(100, 5);
// { epley: 116.7, brzycki: 112.5, lombardi: 117.5, mayhew: 113.3, ... }
The percentages field generates a training load table from 50% to 100% of estimated 1RM — exactly what strength coaches need for programming percentage-based training. The estimateRepsAtWeight function works in reverse, estimating how many reps a lifter can perform at a given percentage of their max.
Body Fat Estimation
Two methods for estimating body composition:
import { calculateBodyFat, getBodyFatCategory } from '@finegym/fitness-calc';
const result = calculateBodyFat('male', 80, {
waistCm: 85,
neckCm: 38,
heightCm: 180,
});
// { bodyFatPercentage: 16.2, fatMass: 13.0, leanMass: 67.0, method: 'us_navy' }
getBodyFatCategory(16.2, 'male');
// 'fitness'
The US Navy circumference method is the primary option, requiring only basic measurements (waist, neck, height, and hip for females). A BMI-derived estimation method is available as a rougher alternative when circumference data isn't available. Categories follow the American Council on Exercise (ACE) classifications: essential, athlete, fitness, average, and obese.
Heart Rate Training Zones
Two models for calculating heart rate training zones:
import { calculateHeartRateZones } from '@finegym/fitness-calc';
// Standard model (percentage of max HR)
const standard = calculateHeartRateZones(30);
// Karvonen model (uses heart rate reserve — more accurate)
const karvonen = calculateHeartRateZones(30, 60, 'karvonen');
Returns five zones from recovery through maximum effort, each with descriptive labels and training guidance. The Karvonen method accounts for individual fitness levels by factoring in resting heart rate, making it more accurate for trained athletes.
Max heart rate estimation uses the Tanaka formula (208 - 0.7 × age) by default, which research shows is more accurate than the traditional Fox formula (220 - age), especially for older adults. Developers can also pass a known max heart rate for users who've had clinical testing.
Calorie Burn Estimation
MET-based calorie calculations for over 30 activities:
import { calculateCaloriesBurned } from '@finegym/fitness-calc';
const result = calculateCaloriesBurned(70, 30, 'running_6mph');
// { totalCalories: 360, caloriesPerMinute: 12.0 }
// Or use a custom MET value
const custom = calculateCaloriesBurned(70, 45, 8.5);
Built-in activities cover the most common gym and outdoor exercises: walking (3 speeds), running (6 speeds), cycling, swimming, weight training, yoga, pilates, HIIT, CrossFit, rowing, jump rope, elliptical, stair climbing, boxing, dancing, hiking, rock climbing, tennis, basketball, soccer, martial arts, and stretching. Developers can also pass numeric MET values for activities not in the built-in list.
MET values are sourced from the Compendium of Physical Activities, the standard reference used in exercise science research. This makes the calorie estimates consistent with what members would see on commercial fitness equipment and wearable devices.
Running Pace and Race Predictions
Complete pace and speed toolkit for running applications:
import { calculatePace, estimateRaceTime } from '@finegym/fitness-calc';
const pace = calculatePace(5, 25, 'km');
// { pacePerKm: '5:00', pacePerMile: '8:03', speedKmh: 12, speedMph: 7.46 }
// Predict marathon time from 5K performance
const marathon = estimateRaceTime(5, 25, 42.195);
// { estimatedMinutes: 236.87, formatted: '3:56:52' }
Race time prediction uses the Riegel formula, which accounts for the nonlinear relationship between race distance and sustainable pace. While no prediction formula is perfect, Riegel's model has been validated across decades of competitive running data.
Additional utilities include pace-to-speed and speed-to-pace conversions, supporting both metric and imperial units.
Additional Calculations
The library also includes:
- Ideal Weight — four formulas (Robinson, Miller, Devine, Hamwi) plus average
- Water Intake — daily hydration recommendations adjusted for activity level
- Unit Conversions — weight (lbs/kg), height (inches/cm/feet+inches), distance (km/miles), temperature (C/F)
How Fitness Businesses Can Use This
While the library is built for developers, it directly benefits fitness businesses in several ways.
Embed Calculators on Your Website
Free online calculators (BMI, TDEE, 1RM, macro calculators) are powerful lead generation tools. They attract organic search traffic from people actively interested in fitness. Using @finegym/fitness-calc, you can build these calculators in hours instead of days, with confidence that the math is scientifically accurate.
For insights on how data-driven approaches improve fitness business outcomes, these calculators serve as both member tools and data collection points.
Build Custom Member Tools
Personal trainers and gym owners can use the library to build tools that enhance the member experience:
- Body composition tracking dashboards
- Personalized nutrition plans based on TDEE and macro calculations
- Strength progression charts using 1RM estimations
- Heart rate zone cards for cardio programming
- Calorie burn summaries for class activities
Power Mobile App Features
If you're developing a member-facing mobile app, these calculations power the features members expect: workout logging with 1RM tracking, nutrition calculators, progress tracking, and training zone displays.
Integrate with Existing Software
The library's zero-dependency design means it integrates cleanly into any JavaScript or TypeScript project — whether that's a React frontend, a Node.js API, or a React Native mobile app. It works with CommonJS and ES modules out of the box.
Technical Details
For developers evaluating the library, here are the specs:
- Language: TypeScript with full type exports
- Dependencies: Zero — no external packages required
- Bundle size: ~20KB minified
- Module formats: CommonJS + ES Modules (dual build via tsup)
- Node.js: Tested on Node 18, 20, and 22
- Testing: 85 tests covering all functions and edge cases
- CI: Automated testing via GitHub Actions on every push and PR
All inputs are validated with descriptive error messages. Invalid weight, height, age, or other parameters throw RangeError exceptions with clear messages explaining what went wrong — making debugging straightforward in development.
Getting Started
Install from npm:
npm install @finegym/fitness-calc
Import what you need:
import {
calculateBMI,
calculateTDEE,
calculateOneRepMax,
calculateMacros,
calculateHeartRateZones,
calculateCaloriesBurned,
} from '@finegym/fitness-calc';
Full documentation, API reference, and examples are available on the GitHub repository.
Contributing
The library is MIT licensed and open to contributions. Whether it's adding new formulas, improving documentation, or reporting bugs, we welcome community involvement. See the contributing guide for details.
Areas where contributions would be especially valuable:
- Additional 1RM formulas from recent research
- Sport-specific calorie burn activities
- Skinfold-based body fat estimation methods
- VO2max estimation formulas
- Pregnancy and pediatric BMI adjustments
The Bigger Picture
This library is one piece of FineGym's commitment to advancing fitness technology. Our gym management platform uses these same calculations to power member-facing features, and we believe making them freely available raises the bar for the entire fitness tech ecosystem.
When developers build better fitness tools, members get better experiences. When members get better experiences, they stay engaged longer. And when fitness businesses retain more members, the entire industry benefits. For advanced fitness software features that leverage these calculations at scale, FineGym provides the complete platform.
If you're building something in the fitness space — whether it's a startup, a gym website feature, or a personal project — give @finegym/fitness-calc a try. Star the repo, file issues, contribute code, and help us build better fitness technology together.
Schedule a demo to see how FineGym's platform leverages these calculations for comprehensive gym management, or start your free trial to experience it firsthand.
