{"id":15536,"library":"bad-words","title":"Bad Words Filter","description":"bad-words is a JavaScript library designed for filtering profanity and undesirable words from text. The current stable version is 4.0.0, which ships with TypeScript types and requires a Node.js environment version 8.0.0 or higher, or an ES2016+ compatible browser environment. While the release cadence is not strictly defined, major versions introduce significant changes, such as the removal of global string prototype modifications and the shift to modern class instantiation. Key features include a highly customizable filter that allows for placeholder overrides, advanced regex-based filtering (including multilingual support), the ability to dynamically add or remove words from the blacklist, and the option to instantiate with an empty list for specific use cases. It also incorporates Soundex support for fuzzy word comparisons, providing a robust and flexible solution for content moderation across various applications.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/web-mech/badwords","tags":["javascript","curse","words","profanity","filter","typescript"],"install":[{"cmd":"npm install bad-words","lang":"bash","label":"npm"},{"cmd":"yarn add bad-words","lang":"bash","label":"yarn"},{"cmd":"pnpm add bad-words","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for creating filter instances. For CommonJS, use 'const { Filter } = require('bad-words');' or 'const Filter = require('bad-words').Filter;' to correctly access the named export.","wrong":"const Filter = require('bad-words')","symbol":"Filter","correct":"import { Filter } from 'bad-words'"},{"note":"TypeScript type definition for the configuration object passed to the Filter constructor.","symbol":"FilterOptions","correct":"import type { FilterOptions } from 'bad-words'"},{"note":"The global String.prototype.clean method was deprecated in v0.5.0 and removed in later major versions. Always instantiate the Filter class and use its 'clean' method.","wrong":"String.prototype.clean('some bad word')","symbol":"clean","correct":"new Filter().clean('some bad word')"}],"quickstart":{"code":"import { Filter } from 'bad-words';\n\n// Create a new filter instance with default settings\nconst filter = new Filter();\n\n// Clean a string, replacing bad words with asterisks\nconst cleanText = filter.clean(\"Don't be an ash0le, this is a heck of a situation.\");\nconsole.log(cleanText);\n// Expected output: \"Don't be an ******, this is a **** of a situation.\"\n\n// Customize the placeholder character\nconst customFilter = new Filter({ placeHolder: 'x' });\nconst customCleanText = customFilter.clean(\"This content is pretty lame.\");\nconsole.log(customCleanText);\n// Expected output: \"This content is pretty xxxx.\"\n\n// Add custom words to the filter's blacklist\ncustomFilter.addWords('lame', 'heck');\nconst updatedCleanText = customFilter.clean(\"This content is pretty lame and a heck of a mess.\");\nconsole.log(updatedCleanText);\n// Expected output: \"This content is pretty xxxx and a xxxx of a mess.\"","lang":"typescript","description":"Demonstrates basic instantiation, cleaning text, customizing the placeholder, and dynamically adding words to the filter list."},"warnings":[{"fix":"Instantiate a new Filter class: 'const filter = new Filter(); filter.clean(text);'","message":"The global String.clean() method was deprecated in v0.5.0 and completely removed in subsequent major versions (likely v1.0.0 or v2.0.0). Direct string prototype modification is no longer supported for filtering.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment is v8.0.0 or higher, or use a build step with Babel for browser compatibility.","message":"As of version 2.0.0, bad-words requires an environment supporting ES2016 features or a transpiler like Babel. Older Node.js versions (below 8.0.0) are not supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always use 'new Filter()' for instantiation, as the factory pattern is no longer supported.","message":"Prior to v1.1.0, the library used a 'factory mess' pattern for instantiation. Since v1.1.0, normal class instantiation via 'new Filter()' is the standard, aligning with modern JavaScript practices.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"const filter = new Filter({ emptyList: true }); filter.addWords('my-custom-bad-word');","message":"When filtering, if you want to allow all words initially and only blacklist specific ones, instantiate the filter with 'emptyList: true' to prevent default bad words from being pre-loaded.","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Instantiate the Filter class: 'const filter = new Filter(); filter.clean(text);'","cause":"Attempting to use the deprecated global String.prototype.clean method.","error":"TypeError: String.prototype.clean is not a function"},{"fix":"Ensure your Node.js project is configured for ESM (e.g., 'type: module' in package.json), or use CommonJS 'const { Filter } = require('bad-words');' for older environments.","cause":"Running ESM 'import' syntax in a CommonJS-only Node.js environment or older browser that doesn't support modules.","error":"SyntaxError: Unexpected token 'export'"},{"fix":"For CommonJS, use 'const { Filter } = require('bad-words');' or 'const Filter = require('bad-words').Filter;' to correctly get the class from the module's exports.","cause":"Attempting to instantiate 'Filter' when it's not correctly imported or accessed from a CommonJS require, often due to incorrect destructuring.","error":"TypeError: Filter is not a constructor"}],"ecosystem":"npm"}