Home Page

The FB2 format parser is based on references from MobileRead Wiki - FB2 and Eng:FictionBook description — FictionBook.

Overview

@lingo-reader/fb2-parser is a parser for .fb2 eBook files, designed to work in both browser and Node.js environments.

Installation

``shell
pnpm install @lingo-reader/fb2-parser
`

Fb2File

Usage in the Browser

`typescript
import { initFb2File } from '@lingo-reader/fb2-parser'
import type { Fb2File, Fb2Spine } from '@lingo-reader/fb2-parser'

async function initFb2(file: File) {
const fb2: Fb2File = await initFb2File(file)
// Get the spine (chapter list)
const spine: Fb2Spine = fb2.getSpine()
// Load the first chapter
const firstChapter = fb2.loadChapter(spine[0].id)
}

// See the Fb2File class for more API details
`

Usage in Node.js

`typescript
import { initFb2File } from '@lingo-reader/fb2-parser'
import type { Fb2File, Fb2Spine } from '@lingo-reader/fb2-parser'

const fb2: Fb2File = await initFb2File('./example/many-languages.fb2')
// Get the spine (chapter list)
const spine: Fb2Spine = fb2.getSpine()
// Load the first chapter
const firstChapter = fb2.loadChapter(spine[0].id)

// See the Fb2File class for more API details
`

initFb2File(file: string | File | Uint8Array, resourceSaveDir?: string): Promise

Initializes and parses an FB2 file. It returns an Fb2File object containing metadata, spine info, and other helper APIs.

Parameters:

- file: string | File | Uint8Array – The FB2 file to load. Can be a file path (Node), File object (Browser), or Uint8Array (both).
- resourceSaveDir?: string – Optional. Used in Node.js to specify where to save resources like images. Defaults to ./images.

Returns:

- Promise – A promise that resolves to the parsed Fb2File instance.

Note:
In the browser, file must be of type File or Uint8Array.
In Node.js, file must be of type string or Uint8Array. Passing the wrong type will result in an error.

Mobi Class

`typescript
class Mobi {
getFileInfo(): FileInfo
getSpine(): Fb2Spine
loadChapter(id: string): Fb2ProcessedChapter | undefined
getToc(): Fb2Toc
getCoverImage(): string
getMetadata(): Fb2Metadata
resolveHref(fb2Href: string): Fb2ResolvedHref | undefined
destroy(): void
}
`

$3

`typescript
interface MobiFileInfo {
// FB2 file name including extension
fileName: string
}
`

Returns basic file information. Currently, only the fileName is provided.

$3

`typescript
interface Fb2SpineItem {
id: string // Chapter ID
}
type Fb2Spine = Fb2SpineItem[]
`

Returns an ordered list of chapters (the "spine"). Each item includes an id that can be passed to loadChapter to load that chapter.

$3

`typescript
interface Fb2CssPart {
id: string
href: string
}
interface Fb2ProcessedChapter {
html: string
css: Fb2CssPart[]
}
`

Loads and processes a chapter by its ID. Returns a structured object containing html and css. Returns undefined if the chapter doesn't exist.

The stylesheet is extracted from FictionBook.stylesheet and shared across all chapters. When loading a chapter, the styles are stored as an object in Fb2ProcessedChapter.css. The id is fixed, while the href is a Blob URL in browser environments and a real file path in Node environments.

The original chapter files are stored in XML format, so converting them to HTML involves transforming both tags and resource paths. The only resources in the chapters are images, and their URLs are automatically converted in the final returned HTML.

Another element that gets transformed is the tag used for internal navigation. The href attribute of these tags is automatically rewritten to a specific format. You can use fb2.resolveHref to parse the rewritten link and extract the corresponding chapter ID and DOM selector.

$3

`typescript
interface Fb2TocItem {
label: string // TOC item label
href: string // Internal FB2 href
}
export type Fb2Toc = Fb2TocItem[]
`

Returns the table of contents. Each item has a label and internal href. Fb2Toc is not nested.

$3

Returns the book's cover image. In the browser, it's a blob URL. In Node.js, it's a file path. If the FB2 file doesn't contain a CoverImage, an empty string is returned.

$3

`typescript
interface Author {
name: string // Full name
firstName: string
middleName: string
lastName: string
nickname?: string
homePage?: string
email?: string
}

interface MobiMetadata {
// title-info
title?: string
type?: string
author?: Author
language?: string
description?: string
keywords?: string
date?: string
srcLang?: string // Source language if translated
translator?: string

// document-info
id?: string
programUsed?: string // Program used to generate the FB2 file
srcUrl?: string // Original source URL of the content
srcOcr?: string // OCR tool or indicator that OCR was used
version?: string
history?: string

// publish-info
bookName?: string
publisher?: string
city?: string
year?: string
isbn?: string
}
`

Returns the book’s metadata.

$3

`typescript
interface Fb2ResolvedHref {
id: string // Chapter ID
selector: string // DOM selector (usable with querySelector)
}
`

Resolves internal FB2 href values (e.g., from ` tags) into a chapter ID and a DOM selector for the in-document anchor.

$3

Cleans up any created blob URLs or saved resources, to avoid memory leaks during parsing and rendering.