Appearance
Client (API)
npm install @gracious.tech/fetch-client
A fetch(bible) collection is just a CDN, so you can't make requests for specific passages, which is where this client comes in.
This client helps to:
- Explore a collection's contents
- Extract specific passages from CDN resources
- Correctly style Bible text with CSS
You can also use this client to access your own self-hosted collection if you choose not to use the official one.
Supported environments
You can use this client both client-side and server-side.
Browsers: ES2015/ES6+
Node: 18+
Usage
The standard way to use the client is to start with a new BibleClient()
and then call fetch_collection()
, which will return a promise for a BibleCollection
which you can use to explore all the languages and translations available, and then call fetch_book(translation, book)
and similar methods to get access to actual Bible content.
Methods starting with fetch_
will make a network request and return a promise, where as methods starting with get_
do not and are synchronous. For methods that return a list (e.g. languages, translations) you can usually pass {object: true}
in the options argument to have them return an object keyed by id
instead.
If your code editor supports Typescript you'll get helpful auto-suggestions that explain all the methods and arguments possible, or alternatively you can also explore the auto-generated docs.
Styles
The client includes a functional stylesheet, meaning styles that are minimalistic and critical for correct display. If you don't include this in your project then, for example, footnotes etc. are going to appear inline and undistinguishable from actual scripture.
If you use a tool like Webpack or Vite then you'll simply need to import '@gracious.tech/fetch-client/dist/client.css'
in a Javascript module, or you could alternatively deploy it with your code and use a <link>
element to include it.
All styles are namespaced under the class fetch-bible
and all subclasses are prefixed with fb-
so that it won't affect your existing styles and they also are unlikely to affect fetch(bible) HTML. So you must embed fetch(bible) HTML under a container element with the class fetch-bible
.
Example
Here is a basic example that outputs a single chapter of a random translation and book.
typescript
import {BibleClient} from '@gracious.tech/fetch-client'
// Init client
const client = new BibleClient()
// Fetch the collection's meta data
const collection = await client.fetch_collection()
// Get what translations are available
const translations = collection.get_translations()
// Get the id of the first translation available
const translation_id = translations[0].id
// Get what books are available for the translation
// (may be whole Bible or may only be e.g. NT)
const books = collection.get_books(translation_id)
// Fetch the contents of the first book
const book = await collection.fetch_book(translation_id, books[0].id)
// Output the HTML of the first chapter of the book
console.log(book.get_chapter(1))
Design
This client has zero dependencies, no differences between the browser and Node versions (no unused code), and is overall very small and fast. It only connects to the endpoints you specify so can be used completely independently of the official fetch(bible) service.