BBCode Parser for JavaScript

Common errors

• TypeError: bbCodeParser.parse is not a function

  cause Incorrect import or CommonJS require statement attempting to call 'parse' directly on the module object instead of the default export.
  fix For CommonJS, use `const bbCodeParser = require('js-bbcode-parser').default;`. For ES Modules, ensure you are importing the default export correctly: `import bbCodeParser from 'js-bbcode-parser';`.

• ReferenceError: BBCodeParser is not defined

  cause Attempting to create a new parser instance using `new BBCodeParser()` without importing the class constructor from its specific path.
  fix Import the class constructor with `import BBCodeParser from 'js-bbcode-parser/src/index.js';`.

• Error: Unknown BBCode tag [mycustomtag]

  cause A BBCode tag was used in the input string that has not been registered with the parser instance.
  fix Register the custom BBCode tag using `parser.addCode('mycustomtag', (content) => `<div>${content}</div>');` before parsing the string.

Warnings

• breaking Major API changes occurred between v2.x and v5.x, particularly concerning parser instantiation and configuration. Users upgrading from v2.x will need to refactor their code, especially around how custom codes are defined and applied.
  Fix: Review the v5.x documentation for new instantiation patterns (e.g., `new BBCodeParser({})`) and configuration methods (e.g., `parser.addCode()` or `parser.setCodes()`).
• gotcha js-bbcode-parser explicitly does not sanitize user input for XSS vulnerabilities. Developers MUST implement their own robust sanitization measures on the output HTML, especially when parsing untrusted user-generated content.
  Fix: Always pass the parsed HTML output through a dedicated HTML sanitization library (e.g., DOMPurify) before rendering it in a browser or storing it. Do not rely on this library for XSS protection.
• gotcha Importing the class constructor `BBCodeParser` requires a specific path (`js-bbcode-parser/src/index.js`). While documented, relying on `src` paths might be less stable than official entry points for future versions.
  Fix: Ensure you use `import BBCodeParser from 'js-bbcode-parser/src/index.js';` for the class constructor. Be aware that changes to internal paths are possible in future major versions.

Install

• npm install js-bbcode-parser npm
• yarn add js-bbcode-parser yarn
• pnpm add js-bbcode-parser pnpm

Imports

• bbCodeParser
  wrong:

  import { bbCodeParser } from 'js-bbcode-parser';

  correct:

  import bbCodeParser from 'js-bbcode-parser';

  This imports the default pre-configured parser instance, ready for use.
• BBCodeParser
  wrong:

  import { BBCodeParser } from 'js-bbcode-parser';

  correct:

  import BBCodeParser from 'js-bbcode-parser/src/index.js';

  This imports the class constructor for creating custom parser instances. Note the explicit path to 'src/index.js'.
• bbCodeParser (CommonJS)
  wrong:

  const bbCodeParser = require('js-bbcode-parser');

  correct:

  const bbCodeParser = require('js-bbcode-parser').default;

  For CommonJS environments, the default export needs to be accessed via '.default' due to ESM interop.

Quickstart

Demonstrates basic usage of the default parser, how to create and configure a custom parser with new BBCode tags, and highlights the critical need for XSS sanitization.

import bbCodeParser from 'js-bbcode-parser';
import BBCodeParser from 'js-bbcode-parser/src/index.js';

// Use the default pre-configured parser
const defaultParsed = bbCodeParser.parse('Hello [b]World[/b]! This is a [color=#FF0000]red[/color] text.');
console.log('Default Parser Output:', defaultParsed);
// Expected: "Hello <strong>World</strong>! This is a <span style="color:#FF0000">red</span> text."

// Create a custom parser instance and add a custom tag
const customParser = new BBCodeParser({});
customParser.addCode(
  'mention',
  (content, attr) => `<a href="/users/${attr.id}">@${content}</a>`,
  ['id'], // Required attribute
  []    // Optional attributes
);

const customParsed = customParser.parse('[mention id=123]Alice[/mention] says hello.');
console.log('Custom Parser Output:', customParsed);
// Expected: "<a href="/users/123">@Alice</a> says hello."

// IMPORTANT: Sanitize user input before parsing, as this library does not provide XSS protection.
const userInput = '[b]Bold text[/b] and potentially malicious <img src=x onerror=alert(1)> content.';
// In a real application, use a dedicated HTML sanitizer library here, e.g., DOMPurify
// Example of basic (non-robust) sanitization (DO NOT rely on this for production XSS prevention!)
const basicSanitizedInput = userInput.replace(/<script[^>]*>.*?<\/script>/gi, '');
const parsedAndSanitized = bbCodeParser.parse(basicSanitizedInput);
console.log('Sanitized Input Output:', parsedAndSanitized);