usfm-js

usfm-js

A bidirectional USFM JSON converter. Parses USFM (Unified Standard Format Marker) Bible translation markup into structured JSON, and serializes JSON back to USFM.

Setup

npm install usfm-js

Usage

var usfm = require('usfm-js');

// Convert USFM to JSON
var json = usfm.toJSON(/** USFM text **/);

// Convert JSON to USFM
var usfmText = usfm.toUSFM(json, { forcedNewLines: true });
// forcedNewLines: if true, word and alignment markers start on a new line (defaults to false)

// Strip all USFM markers, returning plain text
var plain = usfm.removeMarker(usfmText);

Documentation

• USFM format reference: http://ubsicap.github.io/usfm/
• Supported USFM tags are defined in src/js/USFM.js (USFM_PROPERTIES)
• verseObjects.md describes the structure of verse objects
• CLAUDE.md contains an AI-oriented architecture overview

JSON Output Shape

{
  "headers": ["..."],
  "chapters": {
    "1": {
      "1": { "verseObjects": ["..."] },
      "2": { "verseObjects": ["..."] }
    }
  }
}

Each verseObject has the form { type, tag, text, ... }. Words are { type: "word", text, strong, ... }. Alignment milestones (e.g. \zaln) carry their attributes and wrap children in a children array.

Development

npm i          # Install dependencies
npm test       # Run ESLint + full Jest test suite
npm run build  # Transpile src/ → lib/ via Babel

Run a specific test file:

npx jest __tests__/roundTrip.test.js

Run tests matching a name pattern:

npx jest -t "hi_irv"

Run with coverage:

npx jest --coverage

To Publish to NPM:

npm i --legacy-peer-deps && npm run build && npm publish  --tag beta

ESLint uses the Google style guide with the Babel parser (.eslintrc). Linting runs automatically before tests in npm test.

Note: lib/ is generated by npm run build and is the published package entry point. Do not edit files in lib/ directly.

### Summary of changes

- Rewrote the intro to better describe what the library does
- Added `removeMarker` to the **Usage** section (it's part of the public API)
- Replaced the hand-rolled JSON example with the actual output shape produced by the parser
- Expanded the **Development** section with all available commands from `CLAUDE.md` (single test, pattern filter, coverage)
- Added a note about not editing `lib/` directly
- Minor formatting and wording improvements throughout