{"id":15469,"library":"ms.macro","title":"Build-Time MS Converter Macro","description":"ms.macro is a Babel macro designed to convert human-readable time strings (e.g., \"1 day\", \"2 hours\") into their corresponding millisecond values directly at build time. This package, currently at version 2.0.0, aims to eliminate runtime dependencies and shift potential conversion errors from runtime to build time. It is a stable package that typically sees updates driven by changes in Babel's macro API or the underlying `ms` package's parsing logic. Its primary differentiator is its build-time execution, which means that the original `ms` package does not need to be shipped with your production code for these specific conversions, resulting in smaller bundle sizes and improved reliability by catching invalid time strings during compilation rather than during execution. Unlike the original `ms` package, `ms.macro` exclusively supports the string-to-number conversion; it does not offer the reverse conversion from milliseconds to a human-readable string.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/knpwrs/ms.macro","tags":["javascript","babel-macros"],"install":[{"cmd":"npm install ms.macro","lang":"bash","label":"npm"},{"cmd":"yarn add ms.macro","lang":"bash","label":"yarn"},{"cmd":"pnpm add ms.macro","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Babel to process this package as a macro.","package":"babel-plugin-macros","optional":false}],"imports":[{"note":"Primarily designed for ESM usage with Babel and `babel-plugin-macros`. CommonJS `require` is not the intended usage due to its build-time nature.","wrong":"const ms = require('ms.macro');","symbol":"ms","correct":"import ms from 'ms.macro';"},{"note":"The macro also supports tagged template literal syntax for convenience, processing at build time identically to the function call.","symbol":"ms (tagged template)","correct":"import ms from 'ms.macro';\nconst ONE_DAY = ms`1 day`;"},{"note":"If you need both the build-time conversion (ms.macro) and the runtime conversion (original ms package), alias one of the imports. ms.macro uses a default import.","wrong":"import { ms } from 'ms.macro';","symbol":"ms (aliased)","correct":"import msm from 'ms.macro';\nimport ms from 'ms';\nconst value = msm('1h');"}],"quickstart":{"code":"import ms from 'ms.macro';\n\n// Basic function call usage\nconst ONE_HOUR = ms('1 hour');\nconst TWO_DAYS = ms('2 days');\nconst THIRTY_MINUTES = ms('30m');\n\n// Tagged template literal usage\nconst ONE_WEEK = ms`1 week`;\nconst HALF_DAY = ms`0.5d`;\n\nconsole.log(`One hour in milliseconds: ${ONE_HOUR}`); // -> 3600000\nconsole.log(`Two days in milliseconds: ${TWO_DAYS}`); // -> 172800000\nconsole.log(`Thirty minutes in milliseconds: ${THIRTY_MINUTES}`); // -> 1800000\nconsole.log(`One week in milliseconds: ${ONE_WEEK}`); // -> 604800000\nconsole.log(`Half day in milliseconds: ${HALF_DAY}`); // -> 43200000","lang":"javascript","description":"Demonstrates `ms.macro` converting various human-readable time strings into millisecond values at build time, using both function call and tagged template literal syntax."},"warnings":[{"fix":"For converting milliseconds back to a string, you must use the original `ms` package directly (e.g., `import ms from 'ms';`). You can alias `ms.macro` if both are needed.","message":"ms.macro only supports converting time strings to milliseconds. It does NOT support converting milliseconds back into human-readable strings, which is a feature of the original `ms` package. Attempting this will result in a build-time error or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `babel-plugin-macros` is installed (`npm install babel-plugin-macros`) and added to your Babel configuration (e.g., in `.babelrc` or `babel.config.js`).","message":"This macro requires `babel-plugin-macros` to be correctly configured in your Babel setup. Without it, the `ms.macro` import will not be processed, leading to a runtime error or an unresolved import.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always pass a single string representing the time duration to `ms.macro`, e.g., `ms('1 day')` or `ms`1 hour`.","message":"The macro only supports the single string-argument signature. Passing non-string arguments or multiple arguments will result in a build-time error as the macro expects a parseable time string.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Correct the time string to a valid format understood by the `ms` library (e.g., '1 day', '2h', '30m').","cause":"An incorrectly formatted time string was passed to ms.macro, which is caught during the Babel build process.","error":"Error: Invalid time string: '1 da'"},{"fix":"Verify that `babel-plugin-macros` is installed and properly configured in your Babel setup. Ensure you are using `import ms from 'ms.macro';` in an environment where Babel is processing your files.","cause":"This error often occurs when `babel-plugin-macros` is not correctly configured, or `ms.macro` is being used in a CommonJS context without proper transpilation, causing the import to not resolve or the macro transformation to fail.","error":"TypeError: ms is not a function"}],"ecosystem":"npm","meta_description":null}