{"id":10684,"library":"creditcards","title":"Credit Card Utility Methods","description":"The `creditcards` package provides a suite of utility methods for parsing, formatting, and validating credit card numbers, CVCs, and expiration dates. Currently at version 5.0.0, it offers a robust solution for handling common payment-related data operations in applications. While no explicit release cadence is stated, the package is actively maintained and ships with TypeScript types, promoting type safety and improved developer experience. A key differentiator is its modular design, allowing developers to import specific functionalities like `card` or `expiration` individually, and the ability to inject custom card types via the `withTypes` function or by importing individual modules from `creditcards-types` to extend supported card schemas beyond the defaults. It targets modern Node.js environments (>= 18).","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/bendrucker/creditcards","tags":["javascript","credit","cards","validation","formatting","typescript"],"install":[{"cmd":"npm install creditcards","lang":"bash","label":"npm"},{"cmd":"yarn add creditcards","lang":"bash","label":"yarn"},{"cmd":"pnpm add creditcards","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides default and custom card type definitions for advanced usage or extending support for specific card schemes.","package":"creditcards-types","optional":true}],"imports":[{"note":"Primary entry point for card number utilities (parse, format, type, isValid, luhn). ESM is preferred since v5, though CommonJS `require` still works for the main export.","wrong":"const { card } = require('creditcards');","symbol":"card","correct":"import { card } from 'creditcards';"},{"note":"Provides CVC validation utilities. Follows the same import pattern as 'card'.","wrong":"const { cvc } = require('creditcards');","symbol":"cvc","correct":"import { cvc } from 'creditcards';"},{"note":"Offers utilities for parsing and validating expiration months and years. Follows the same import pattern as 'card'.","wrong":"const { expiration } = require('creditcards');","symbol":"expiration","correct":"import { expiration } from 'creditcards';"},{"note":"When importing individual modules like 'creditcards/card', they typically expose a default function. This pattern is useful for injecting custom card types.","wrong":"import { Card } from 'creditcards/card';","symbol":"Card","correct":"import Card from 'creditcards/card';"}],"quickstart":{"code":"import { card, cvc, expiration, withTypes } from 'creditcards';\nimport { visa, mastercard } from 'creditcards-types';\n\n// --- Card Utilities ---\nconst rawCardNumber = '  4242-4242-4242-4242  ';\nconst parsedCardNumber = card.parse(rawCardNumber); // '4242424242424242'\nconst formattedVisa = card.format(parsedCardNumber); // '4242 4242 4242 4242'\nconst cardType = card.type(parsedCardNumber); // 'visa'\nconst isValidLuhn = card.luhn(parsedCardNumber); // true\nconst isValidCard = card.isValid(parsedCardNumber); // true\nconst isValidVisa = card.isValid(parsedCardNumber, 'visa'); // true\n\nconsole.log(`Parsed Card: ${parsedCardNumber}`);\nconsole.log(`Formatted Card: ${formattedVisa}`);\nconsole.log(`Card Type: ${cardType}`);\nconsole.log(`Luhn Valid: ${isValidLuhn}`);\n\n// --- CVC Utilities ---\nconst cvcValue = '123';\nconst isValidCVC = cvc.isValid(cvcValue, 'visa'); // true\nconsole.log(`CVC Valid for Visa: ${isValidCVC}`);\n\n// --- Expiration Utilities ---\nconst currentMonth = new Date().getMonth() + 1;\nconst currentYear = new Date().getFullYear();\nconst futureYear = currentYear + 5;\n\nconst isMonthValid = expiration.month.isValid(currentMonth); // true\nconst isYearValid = expiration.year.isValid(futureYear); // true\nconst isPast = expiration.isPast(currentMonth - 1, currentYear); // true (assuming currentMonth > 1)\n\nconsole.log(`Expiration Month Valid: ${isMonthValid}`);\nconsole.log(`Expiration Year Valid: ${isYearValid}`);\nconsole.log(`Is past (last month): ${isPast}`);\n\n// --- Using custom types (requires 'creditcards-types') ---\nconst customCardModule = withTypes([visa, mastercard]);\nconst isAmexWithCustomTypes = customCardModule.card.isValid('378282246310005', 'american-express'); // false if only visa/mastercard are included\nconsole.log(`Is Amex valid with custom types (only Visa/MC): ${isAmexWithCustomTypes}`);","lang":"typescript","description":"This quickstart demonstrates common usage patterns for credit card validation and formatting, including parsing, formatting, type detection, Luhn algorithm check, CVC validation, and expiration date checks. It also shows how to customize card types using `withTypes`."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18 or newer, or pin `creditcards` to a version less than 5.0.0 (e.g., `creditcards@^4`).","message":"Version 5.0.0 elevates the minimum Node.js requirement to >= 18. Applications running on older Node.js versions will need to upgrade their environment or stick to an earlier major version of `creditcards`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always pass the output of `card.parse(number)` to `card.type()` or `card.isValid()` to prevent unexpected behavior with non-numeric characters.","message":"When using `card.type()` or `card.isValid()`, ensure the card number is sanitized first using `card.parse()`. These methods expect a purely numeric string without spaces or punctuation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `import Card from 'creditcards/card';` instead of `import { Card } from 'creditcards/card';` for individual module imports. Review the README for correct import patterns for specific sub-modules.","message":"Individual module imports (e.g., `creditcards/card`) typically export a default function or object, not named exports. Incorrectly using named imports for these paths will lead to `TypeError: (0 , creditcards_card__WEBPACK_IMPORTED_MODULE_0__.Card) is not a function` or similar errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For strict validation of a complete card number, ensure `eager` is `false` or omitted. Use `card.isValid()` for definitive validity checks.","message":"The `eager` parameter for `card.type(number, eager)` will match partial card numbers, which can be useful for UI feedback during input but should not be relied upon for final, strict validation of a complete card number.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `import { Card } from 'creditcards/card';` to `import Card from 'creditcards/card';`.","cause":"Attempting to import a default export from a sub-module as a named export.","error":"TypeError: (0 , creditcards_card__WEBPACK_IMPORTED_MODULE_0__.Card) is not a function"},{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import` statements. If sticking to CommonJS, verify the specific `creditcards` version and import path support `require()` for the module you're trying to access.","cause":"Attempting to `require()` an ESM-only module or using CJS `require` in an ESM project for a package that strictly enforces ESM.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not supported"},{"fix":"Always sanitize the card number using `card.parse()` before passing it to `card.type()` or `card.isValid()`: `card.type(card.parse(inputNumber))`.","cause":"`card.type` and `card.isValid` expect a purely numeric string, not one with spaces or other characters.","error":"card.type is undefined when passing a number like '4242 4242 4242 4242'"}],"ecosystem":"npm"}