Modern TypeScript library for accessing the complete Hebrew Bible (Tanach) text.
- Complete Tanach text (Torah, Neviim, Kesuvim)
- Modern ES modules with TypeScript support
- Optimized data format (25% smaller than original)
- Type-safe API
- Works in Node.js and browsers
- Full test coverage
npm install @shafeh/tanachimport { tanach, getChapter, getBooks } from '@shafeh/tanach';
// Get a specific verse
const verse = tanach('Bereishit', 1, 1);
console.log(verse?.text); // בְּרֵאשִׁ֖ית בָּרָ֣א אֱלֹהִ֑ים אֵ֥ת הַשָּׁמַ֖יִם וְאֵ֥ת הָאָֽרֶץ:
console.log(verse?.bookEnglish); // Genesis
// Get an entire chapter
const chapter = getChapter('Bereishit', 1);
console.log(chapter?.length); // 31 verses
// Get all available books
const books = getBooks();
console.log(books); // ['Bereishit', 'Shemot', ...]Get a specific verse.
Parameters:
book- Book name (transliterated Hebrew, e.g., "Bereishit")chapter- Chapter numberverse- Verse number
Returns: VerseResult | null
Get all verses in a chapter.
Returns: VerseResult[] | null
Get all available book names.
Returns: string[]
Get metadata for a specific book.
Returns: BookMeta | null
Array of the three main sections: ['Torah', 'Neviim', 'Kesuvim']
Helper functions that return section names.
Extract only Hebrew letters from text, removing nekudot (vowel points) and cantillation marks.
Parameters:
text- Hebrew text with diacritical marks
Returns: string - Text with only Hebrew letters
Example:
extractHebrewLetters("בְּרֵאשִׁ֖ית"); // Returns "בראשית"Find all verses that begin with a specific Hebrew letter.
Parameters:
letter- Hebrew letter to search for (e.g., "א", "ב")options.books- Optional array of book names to limit searchoptions.maxResults- Optional maximum number of results
Returns: VerseResult[]
Example:
// Find all verses starting with aleph
const verses = findPesukimByStartingLetter("א");
// Find verses starting with bet in Torah books only
const verses = findPesukimByStartingLetter("ב", {
books: ["Bereishit", "Shemot", "Vayikra", "Bamidbar", "Devarim"]
});
// Find first 50 verses starting with gimmel
const verses = findPesukimByStartingLetter("ג", { maxResults: 50 });Find all verses that begin with one Hebrew letter and end with another. This is commonly used for the minhag (custom) of saying a pasuk for one's name in Shemona Esre (the Amidah prayer).
Parameters:
startLetter- Hebrew letter the verse should start withendLetter- Hebrew letter the verse should end withoptions.books- Optional array of book names to limit searchoptions.maxResults- Optional maximum number of results
Returns: VerseResult[]
Example:
// Find verses for the name "David" (דוד - starts with dalet, ends with dalet)
const verses = findPesukimByName("ד", "ד");
// Find verses for the name "Avraham" (אברהם - starts with aleph, ends with mem)
const verses = findPesukimByName("א", "ם");
// Search only in Tehillim (Psalms)
const verses = findPesukimByName("י", "ה", { books: ["Tehillim"] });Note: This function correctly handles Hebrew final forms (ך, ם, ן, ף, ץ) when matching end letters. Results are automatically sorted with preferred/traditional verses first.
Get the traditional/preferred pasuk for a given name. This returns the verse from traditional lists that is commonly used for the minhag.
Parameters:
startLetter- First letter of the nameendLetter- Last letter of the name
Returns: VerseResult | null - The preferred verse with preferred: true, or null if none exists
Example:
// Get the traditional verse for "David" (דוד)
const verse = getPreferredPasukForName("ד", "ד");
if (verse) {
console.log(`${verse.book} ${verse.chapter}:${verse.verse}`);
console.log(verse.text);
console.log(verse.preferred); // true
}
// Get all options including the preferred one
const allVerses = findPesukimByName("א", "א");
const preferred = allVerses.find(v => v.preferred);
// The preferred verse is automatically sorted first in the resultsThe library includes a curated list of traditional verses for the minhag of saying a pasuk for one's name. These verses are:
- Automatically marked with
preferred: truein search results - Sorted first in
findPesukimByName()results - Accessible directly via
getPreferredPasukForName() - Based on traditional lists used in various Jewish communities
You can extend the preferred verses list by editing scripts/preferred-verses-input.json and running:
node scripts/process-preferred-verses.cjsinterface VerseResult {
book: string;
bookHebrew: string;
bookEnglish: string;
chapter: number;
verse: number;
text: string;
preferred?: boolean; // True if this is a traditional/preferred verse for a name
}
interface BookMeta {
he: string; // Hebrew (בראשית)
en: string; // English (Genesis)
heT: string; // Transliterated (Bereishit)
}# Install dependencies
npm install
# Run tests
npm test
# Build
npm run build
# Watch mode for tests
npm run test:watchThe package is automatically published to npm when:
- Release is created: Create a new release on GitHub, and the package will be automatically published
- Manual trigger: Go to Actions → "Publish to npm" → Run workflow
Set up the NPM_TOKEN secret in your GitHub repository:
- Generate an npm access token at https://www.npmjs.com/settings/[username]/tokens
- Add it as a repository secret named
NPM_TOKEN - Ensure the token has publish permissions
# Bump version
npm version patch|minor|major
# Build and publish
npm run build
npm publish --access publicThe repository includes two GitHub Actions workflows:
- CI (
.github/workflows/ci.yml): Runs tests on Node.js 18, 20, and 22 for all PRs and pushes to main - Publish (
.github/workflows/npm-publish.yml): Publishes package to npm on releases
The library uses an optimized compressed format that reduces file size by ~25% compared to the original flat array structure. Data is nested by book and chapter for efficient lookups.
ISC