zxcvbn-typescript

Common errors

• TypeError: zxcvbn is not a function

  cause This typically occurs due to an incorrect import statement (e.g., attempting a named import when the library provides a default export) or CommonJS/ESM module interop issues in your build or runtime environment.
  fix If using ESM, ensure you use `import zxcvbn from 'zxcvbn-typescript';`. If using CommonJS, use `const zxcvbn = require('zxcvbn-typescript');`. Also, check your `tsconfig.json`'s `moduleResolution` and `module` options for compatibility.

• TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.

  cause Passing a potentially `undefined` or `null` value as the password or an element within `userInputs` without proper type narrowing, which is enforced more strictly by TypeScript, especially in v5.0.0 and later.
  fix Ensure that the `password` argument and all elements within the `userInputs` array are explicitly of type `string`. Use conditional checks (`if (password) { ... }`) or non-null assertion operators (`password!`) after confirming values are present.

• Error: Cannot find module 'zxcvbn-typescript'

  cause The package has not been installed, or there is a module resolution conflict within your build tool (e.g., Webpack, Rollup) or Node.js runtime environment.
  fix Run `npm install zxcvbn-typescript` or `yarn add zxcvbn-typescript`. Confirm your `tsconfig.json` `compilerOptions.moduleResolution` (e.g., 'NodeNext' for modern Node.js or 'bundler' for bundlers) and ensure your package manager can correctly resolve the module.

Warnings

• breaking Version 5.0.0 introduced a complete port to TypeScript. This transition may lead to stricter type checks and potential build issues in existing JavaScript projects without proper TypeScript configuration or type declarations. For projects previously relying on `@types/zxcvbn` for type definitions, these are now natively bundled with `zxcvbn-typescript` v5.x.
  Fix: Ensure your project's `tsconfig.json` is correctly configured for TypeScript. If migrating from a pre-v5 JavaScript version, review your type usage and update imports to align with the new TypeScript-first approach. For CommonJS consumers, verify module resolution settings.
• gotcha Performance can be affected when evaluating extremely long passwords (e.g., hundreds of characters) or performing frequent checks in performance-critical sections of an application. The algorithm is optimized for interactive, user-facing feedback, not high-throughput batch processing of arbitrary length strings.
  Fix: For very long inputs, consider truncating the password to a reasonable length (e.g., 100-256 characters) before passing it to `zxcvbn`. Implement throttling or debouncing for interactive UI elements that trigger password evaluations to prevent excessive computations.
• gotcha While `zxcvbn-typescript` generally bundles its dictionary data, some modular `zxcvbn` implementations (such as `@zxcvbn-ts/core`) split language and dictionary data into separate packages to reduce initial bundle size. If you encounter unexpected 'Top 10 common password' warnings or notice less effective pattern matching, confirm that all necessary dictionary and language data is being loaded and configured correctly.
  Fix: Verify that `zxcvbn-typescript` is correctly installed. If using a custom build or a different `zxcvbn` variant, consult its documentation to ensure all required dictionary and language packages are installed and explicitly configured for comprehensive scoring.

Install

• npm install zxcvbn-typescript npm
• yarn add zxcvbn-typescript yarn
• pnpm add zxcvbn-typescript pnpm

Imports

• zxcvbn
  wrong:

  import { zxcvbn } from 'zxcvbn-typescript';

  correct:

  import zxcvbn from 'zxcvbn-typescript';

  The primary zxcvbn function is typically a default export since v5.0.0, aligning with previous major versions of the zxcvbn project. Using a named import will result in `zxcvbn is not a function`.
• ZXCVBNResult

  import type { ZXCVBNResult } from 'zxcvbn-typescript';

  Importing the `ZXCVBNResult` type provides strong type checking for the object returned by the `zxcvbn` function. This type is generally exposed as a named export from the main module.
• zxcvbn (CommonJS)

  const zxcvbn = require('zxcvbn-typescript');

  While primarily an ESM-first library since v5.0.0 due to its TypeScript rewrite, CommonJS `require` is still supported in environments with proper interop. Be mindful of module resolution settings.

Quickstart

Demonstrates how to import the `zxcvbn` function, evaluate a password, and interpret the returned strength score, guess estimations, and verbal feedback, including handling optional user inputs for enhanced security.

import zxcvbn from 'zxcvbn-typescript';
import type { ZXCVBNResult } from 'zxcvbn-typescript';

/**
 * Evaluates a password's strength and logs detailed feedback.
 * @param password The password string to evaluate.
 * @param userInputs Optional array of strings (e.g., username, email) to penalize if found in the password.
 * @returns The detailed `ZXCVBNResult` object.
 */
function evaluatePassword(password: string, userInputs: string[] = []): ZXCVBNResult {
  const result = zxcvbn(password, userInputs);
  
  console.log(`Password: "${password}"`);
  console.log(`Score (0-4): ${result.score}`);
  console.log(`Estimated guesses: ${result.guesses.toLocaleString()}`);
  console.log(`Feedback: ${result.feedback.warning || 'Looks good!'}`);
  result.feedback.suggestions.forEach(suggestion => {
    console.log(`- Suggestion: ${suggestion}`);
  });

  // Accessing various crack time estimations
  console.log(`\nCrack Times:`);
  console.log(`  Online (throttled): ${result.crack_times_display.online_throttling_100_per_hour}`);
  console.log(`  Offline (slow hash): ${result.crack_times_display.offline_slow_hashing_1e4_per_second}`);
  
  return result;
}

// Example usage with different password strengths and user inputs
const weakPassword = 'password123';
const moderatePassword = 'MySecretPassword1!';
const strongPassword = 'correct horse battery staple';
const userEmail = 'test@example.com';
const userName = 'JohnDoe';

console.log('--- Evaluating Weak Password ---');
evaluatePassword(weakPassword, [userEmail, userName]);

console.log('\n--- Evaluating Moderate Password ---');
evaluatePassword(moderatePassword, ['mysecret', 'password']);

console.log('\n--- Evaluating Strong Password ---');
evaluatePassword(strongPassword, ['correcthorse']);