Registry / auth-security / zxcvbn-typescript

zxcvbn-typescript

JSON →
library5.0.1jsnpmunverified

The `zxcvbn-typescript` library offers a realistic and robust approach to password strength estimation, ported to TypeScript from Dan Wheeler's original zxcvbn project. It evaluates password quality by analyzing various patterns, including common words, names, dates, sequences, keyboard patterns, and leetspeak, providing a numerical score and targeted verbal feedback to guide users. The current stable version is 5.0.1. With its v5.0.0 release, the library was fully converted to TypeScript, enhancing type safety and maintainability for modern development environments. While a strict release cadence isn't defined, updates typically align with algorithm refinements or significant refactors. Its key differentiator remains its comprehensive pattern-matching capabilities, which often provide more nuanced security assessments than simpler entropy-based methods.

npm install zxcvbn-typescript
INSTALL
IMPORT
SIG · ZXCVBN-TYPESCRIPT
Z
zxcvbn-typescript
auth-securityjavascriptv5.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

zxcvbn
import zxcvbn from 'zxcvbn-typescript';
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.

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']);
Debug
Known issues
breakingVersion 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.
affects: >=5.0.0
gotchaPerformance 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.
affects: >=1.0.0
gotchaWhile `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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: zxcvbn is not a function
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'.
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'
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.
Upgrade
Version history
5.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
39 hits · last 30 days
node
32
OpenAI (training)
1
Resources