Herb JavaScript Bindings

Herb provides official JavaScript bindings as NPM packages, published under the @herb-tools organization. These packages are available for installation via npmjs.org using any package manager of your choice.

Herb supports both browser and Node.js environments with separate packages, ensuring optimized compatibility for each platform.

More Language Bindings

Herb also has bindings for:

• Ruby
• Java
• Rust

Installation

Browser usage

Installing the NPM Package

To use Herb in a browser environment, install the @herb-tools/browser package:

npm

npm add @herb-tools/browser

pnpm

pnpm add @herb-tools/browser

yarn

yarn add @herb-tools/browser

bun

bun add @herb-tools/browser

Importing in Your Project

Import the Herb object into your project:

async/await

import { Herb } from "@herb-tools/browser"

await Herb.load()

Herb.parse("content")

Promise

import { Herb } from "@herb-tools/browser"

Herb.load().then(() => {
  Herb.parse("content")
})

You are now ready to parse HTML+ERB in the browser using JavaScript.

---

Node.js usage

Installing the NPM Package

To use Herb in a Node.js environment, install the @herb-tools/node package:

npm

npm add @herb-tools/node

pnpm

pnpm add @herb-tools/node

yarn

yarn add @herb-tools/node

bun

bun add @herb-tools/node

Importing in Your Project

Import the Herb object into your project:

async/await

import { Herb } from "@herb-tools/node"

await Herb.load()

Herb.parse("content")

Promise

import { Herb } from "@herb-tools/node"

Herb.load().then(() => {
  Herb.parse("content")
})

You are now ready to parse HTML+ERB in Node.js.

Using Unreleased Commits

Each commit on the main branch and pull requests with approved reviews are published to pkg.pr.new. You can install preview packages directly from commits or PRs:

npm

npm i https://pkg.pr.new/@herb-tools/core@{commit}

pnpm

pnpm add https://pkg.pr.new/@herb-tools/core@{commit}

yarn

yarn add https://pkg.pr.new/@herb-tools/core@{commit}

bun

bun add https://pkg.pr.new/@herb-tools/core@{commit}

Replace {commit} with the short commit SHA (e.g., 0d2eabe) or branch name (e.g., main).

Running CLI Tools from Previews

You can also run CLI tools directly from preview releases without installing:

Linter

npx https://pkg.pr.new/@herb-tools/linter@{commit} template.html.erb

Formatter

npx https://pkg.pr.new/@herb-tools/formatter@{commit} template.html.erb

Language Server

npx https://pkg.pr.new/@herb-tools/language-server@{commit} --stdio

This is perfect for testing bug fixes or new features before they're officially released!

The API

Regardless of whether you imported Herb from @herb-tools/browser or @herb-tools/node, the API is the same. The API pages document each call once, with a JavaScript tab alongside the other bindings.

Page	JavaScript methods
Parsing	Herb.parse, Herb.parseFile
Lexing	Herb.lex, Herb.lexFile
Extracting Ruby and HTML	Herb.extractRuby, Herb.extractHTML
Working with the tree	Visitor, locate
Versions	Herb.version

Herb.load() has to resolve before any of them are called. The file variants, parseFile and lexFile, throw in the browser package, which has no file access.