bad-words

library4.0.0jsnpmunverified

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.

communication

npm install bad-words

github ↗package ↗

INSTALL

IMPORT

SIG · BAD-WORDS

bad-words

communicationjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Filter

✓ import { Filter } from 'bad-words'

✗ const Filter = require('bad-words')

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.

FilterOptions

✓ import type { FilterOptions } from 'bad-words'

TypeScript type definition for the configuration object passed to the Filter constructor.

clean

✓ new Filter().clean('some bad word')

✗ String.prototype.clean('some bad word')

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.

Demonstrates basic instantiation, cleaning text, customizing the placeholder, and dynamically adding words to the filter list.

import { Filter } from 'bad-words'; // Create a new filter instance with default settings const filter = new Filter(); // Clean a string, replacing bad words with asterisks const cleanText = filter.clean("Don't be an ash0le, this is a heck of a situation."); console.log(cleanText); // Expected output: "Don't be an ******, this is a **** of a situation." // Customize the placeholder character const customFilter = new Filter({ placeHolder: 'x' }); const customCleanText = customFilter.clean("This content is pretty lame."); console.log(customCleanText); // Expected output: "This content is pretty xxxx." // Add custom words to the filter's blacklist customFilter.addWords('lame', 'heck'); const updatedCleanText = customFilter.clean("This content is pretty lame and a heck of a mess."); console.log(updatedCleanText); // Expected output: "This content is pretty xxxx and a xxxx of a mess."

Debug

Known issues

breakingThe 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.

fix

Instantiate a new Filter class: 'const filter = new Filter(); filter.clean(text);'

affects: >=1.0.0

breakingAs 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.

fix

Ensure your Node.js environment is v8.0.0 or higher, or use a build step with Babel for browser compatibility.

affects: >=2.0.0

gotchaPrior 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.

fix

Always use 'new Filter()' for instantiation, as the factory pattern is no longer supported.

affects: <1.1.0

gotchaWhen 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.

fix

const filter = new Filter({ emptyList: true }); filter.addWords('my-custom-bad-word');

affects: >=0.5.0

Errors

Common errors & fixes

TypeError: String.prototype.clean is not a function

Attempting to use the deprecated global String.prototype.clean method.

fix

Instantiate the Filter class: 'const filter = new Filter(); filter.clean(text);'

SyntaxError: Unexpected token 'export'

Running ESM 'import' syntax in a CommonJS-only Node.js environment or older browser that doesn't support modules.

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.

TypeError: Filter is not a constructor

Attempting to instantiate 'Filter' when it's not correctly imported or accessed from a CommonJS require, often due to incorrect destructuring.

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.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

48 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/web-mech/badwords ↗

packagehttps://www.npmjs.com/package/bad-words ↗