A username and display-name blocklist for apps that need to prevent reserved names, unsafe names, impersonation names, route collisions, and other names that should not be allowed during account creation.
npm install username-blocklistimport { checkBlockedName, isBlockedName } from 'username-blocklist';
const blocked = isBlockedName('admin');
// true
const result = checkBlockedName('@DenOfficial');
// {
// blocked: true,
// reason: 'exact' | 'contains',
// normalizedName: 'denofficial',
// matchedTerm: 'denofficial'
// }For user-facing errors, do not reveal which term was matched. Use one generic error string, such as:
'Username is not available, try another please'That prevents users from reverse-engineering the blocklist and avoids creating unnecessary arguments with users about specific terms.
The package uses two matching modes:
BLOCKED_NAME_EXACT_TERMS— blocks only when the normalized name equals the term.BLOCKED_NAME_CONTAINS_TERMS— blocks when the normalized name contains the term anywhere.
This keeps short/system terms from causing false positives while still catching severe or impersonation terms inside longer names.
Before checking, names are normalized by:
- Unicode NFKC normalization
- trimming whitespace
- removing leading
@symbols - removing invisible/control characters
- lowercasing
The package does not perform aggressive leetspeak conversion because that can create surprising false positives. Common variants should be added directly to the list.
Returns true if the name is blocked.
isBlockedName('admin');Returns a structured result.
checkBlockedName('admin');Returns the normalized version of a name.
normalizeName(' @Admin '); // "admin"You can provide your own arrays if you want to extend or override the defaults:
checkBlockedName('example', {
exactTerms: ['example'],
containsTerms: ['badterm'],
});npm install
npm test
npm run typecheck
npm run build- Create a new folder on your computer named
username-blocklist. - Copy these files into that folder.
- Open the folder in VS Code.
- Run:
git init
git add .
git commit -m "Initial username blocklist package"- Create a new GitHub repo.
- Do not add a README/license/gitignore on GitHub if you already copied these files.
- Connect and push:
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/username-blocklist.git
git push -u origin mainMIT