The tiniest, fastest, fully type-safe unit conversion library you'll actually want to use.
At some point, every developer has written something like const km = miles * 1.60934. It works. Until it doesn't — a wrong constant, a missing unit, a runtime error in production. The convert npm package exists to eliminate that entire class of bugs with zero overhead.
What Is convert?
convert is a TypeScript-first unit conversion library designed around one principle: if it compiles, it's correct. It supports lengths, weights, time, temperature, data sizes, speed, pressure, and more — all with full type inference at build time.
Unlike most conversion libraries, convert validates units at compile time. Typos and impossible conversions become TypeScript errors, not runtime bugs.
Installation
Terminal
npm
npm install convert
yarn
yarn add convert
pnpm
pnpm add convert
Basic Usage
The API is intentionally minimal. You call convert(value, unit).to(targetUnit) and get back a number.
TypeScript
import { convert } from 'convert';
// Length
convert(5, 'miles').to('km'); // → 8.04672
convert(180, 'cm').to('feet'); // → 5.905
// Weight
convert(70, 'kg').to('pounds'); // → 154.32
// Time (duration strings!)
import { convertMany } from 'convert';
convertMany('4d 16h').to('minutes'); // → 6720
// Temperature
convert(100, 'celsius').to('fahrenheit'); // → 212
Why Not Just Use a Formula?
Hardcoded formulas are invisible to your type system. You can pass "feets" (a typo) and JavaScript won't complain until your user sees NaN. With convert, that typo is a red underline in your editor before you even save the file.
TypeScript — type safety in action
// ✅ This works fine
convert(10, 'meters').to('feet');
// ❌ TypeScript error: Argument of type '"feets"'
// is not assignable to parameter of type 'LengthUnit'
convert(10, 'meters').to('feets');
// ❌ TypeScript error: can't mix unit categories
convert(10, 'meters').to('pounds');
Performance Benchmarks
The library is benchmarked against other popular alternatives. The results are not close.
Library Time per op Bundle size Dependencies
convert ~0.8 µs ~5 kB 0
mathjs ~180 µs ~150 kB many
units-converter ~25 µs ~18 kB few
js-quantities ~40 µs ~28 kB few
Why is it so fast?
Two reasons: first, it has zero runtime dependencies. Second, when you use it with Next.js or Vite, the conversions are pre-calculated at build time — meaning the final bundle shipped to users contains the raw number, not any conversion code at all.
Real-World Example: A Shipping Calculator
Imagine you're building an e-commerce app that receives weight in kilograms from your database but your shipping API expects pounds, and your UI displays ounces for small items.
TypeScript — shipping utility
import { convert } from 'convert';
interface ShippingItem {
name: string;
weightKg: number;
}
function getShippingPayload(item: ShippingItem) {
return {
name: item.name,
// API expects pounds
weightLbs: convert(item.weightKg, 'kg').to('pounds'),
// UI displays ounces for items under 1kg
displayOz: convert(item.weightKg, 'kg').to('ounces'),
};
}
// Usage
getShippingPayload({ name: 'Notebook', weightKg: 0.45 });
// → { name: 'Notebook', weightLbs: 0.992, displayOz: 15.87 }
Using convertMany for Duration Strings
One underrated feature is convertMany, which parses human-readable duration strings. Incredibly useful for config files, CLIs, and user-facing input fields.
TypeScript
import { convertMany } from 'convert';
convertMany('1h 30m').to('seconds'); // → 5400
convertMany('2d 6h').to('hours'); // → 54
convertMany('90s').to('minutes'); // → 1.5
Tree-Shaking and Bundle Impact
Because convert is marked as side-effect free in its package.json, modern bundlers will eliminate any unit categories you never use. If your app only converts lengths and weights, the temperature and pressure code is never included in your bundle.
With Next.js or Vite, convert(5, 'miles').to('km') in a component gets replaced by the literal 8.04672 at build time. Zero runtime cost.
Should You Use It?
If your codebase has any of the following, convert will improve it:
The code you probably have right now
// Magic numbers scattered everywhere
const speedMs = speedKmh / 3.6;
const inches = cm * 0.393701;
const gb = bytes / (1024 * 1024 * 1024);
// Replace with:
import { convert } from 'convert';
const speedMs = convert(speedKmh, 'km/h').to('m/s');
const inches = convert(cm, 'cm').to('inches');
const gb = convert(bytes, 'B').to('GB');
TL;DR
convert is the right tool when you need unit conversion in TypeScript or JavaScript. It's smaller than a single React component, faster than any alternative, and catches unit errors before your code runs. Install it, replace your magic numbers, and never think about * 0.621371 again.
https://fast-convert.net
Top comments (0)