# usfm-js

> A small library that provides functions to convert usfm to JSON and vice-versa

Latest version **3.5.0** (published 2026-05-23) · ISC license · 0 weekly downloads

## Install

```sh
npm install usfm-js
pnpm add usfm-js
yarn add usfm-js
bun add usfm-js
```

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 3.5.0 |
| Published | 2026-05-23 |
| First published | 2017-07-20 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 1.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | @unfoldingword |
| Maintainers | neutrinog, jakobaleksandrovich, klappy, photo-nomad, richmahn, mandolyte, jag3773, mvahowe, larsgson, abelpz, eliaspinero, macolon |
| Keywords | USFM, Scripture, JSON, Bible |

## Links

- npm: https://www.npmjs.com/package/usfm-js
- Repository: https://github.com/translationCoreApps/usfm-js
- Homepage: https://github.com/translationCoreApps/usfm-js#readme
- Issues: https://github.com/translationCoreApps/usfm-js/issues
- npm.io page: https://npm.io/package/usfm-js

## Dependencies (1)

- [lodash.clonedeep](https://npm.io/package/lodash.clonedeep.md) ^4.5.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.5.0 (latest) — 2026-05-23
- 3.5.0-beta.2 (beta) — 2026-05-23
- 3.4.2-alpha (alpha) — 2022-11-23
- 1.0.8 (release-v1.0.2) — 2018-11-02
- 3.4.3 — 2024-08-20
- 3.4.3-beta.7 — 2024-08-20
- 3.4.3-beta.6 — 2024-08-16
- 3.4.3-beta.5 — 2024-08-16
- 3.4.3-beta.4 — 2024-08-16
- 3.4.3-beta.3 — 2024-08-16
- 3.4.3-beta.2 — 2024-08-15
- 3.4.3-beta — 2024-08-15
- 3.4.2 — 2023-01-02
- 2.1.1-alpha — 2022-11-23
- 3.4.1 — 2022-07-19
- … 67 more at https://npm.io/package/usfm-js/versions

## README

# usfm-js

[![Build Status](https://api.travis-ci.org/translationCoreApps/usfm-js.svg?branch=develop)](https://travis-ci.org/translationCoreApps/usfm-js) 
[![npm](https://img.shields.io/npm/dt/usfm-js.svg)](https://www.npmjs.com/package/usfm-js)
[![npm](https://img.shields.io/npm/v/usfm-js.svg)](https://www.npmjs.com/package/usfm-js)
[![codecov](https://codecov.io/gh/translationCoreApps/usfm-js/branch/master/graph/badge.svg)](https://codecov.io/gh/translationCoreApps/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

```bash
npm install usfm-js
```


## Usage

```js
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

```json
{
  "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

```shell script
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:

```shell script
npx jest __tests__/roundTrip.test.js
```


Run tests matching a name pattern:

```shell script
npx jest -t "hi_irv"
```


Run with coverage:

```shell script
npx jest --coverage
```

To Publish to NPM:
```bash
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
```

---
_Source: https://npm.io/package/usfm-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._