Abra sua Bíblia!

A website to read the Bible in the translation of your choice: https://www.abrasuabiblia.com.br

Built with TypeScript and Vite, deployed on Vercel.

Language policy

All source code and documentation in this project (comments, identifiers, tests, README and any other docs) must be written in English. The only exception is the user interface: the texts the site shows to its users stay in Brazilian Portuguese, as do the Bible data and the test fixtures that depend on them.

Development

Requires Node.js 24.

npm install
npm run dev        # development server
npm run build      # production build into dist/
npm run preview    # serves the production build (needed to test the service worker)

To reproduce the Vercel environment locally (uses vercel.json):

npm i -g vercel
vercel dev         # development
vercel build       # build identical to production, into .vercel/output

Tests

npm run check      # typecheck + lint + unit tests
npm run test:e2e   # end-to-end tests (Playwright) against the production build

On the first run of the E2E tests, install the browser with npx playwright install chromium.

Dependencies and npm audit

No production dependency has a known vulnerability (npm audit --omit=dev). What npm audit still lists is only in the build tooling and does not ship to the site.

package.json pins two versions (overrides) because of transitive dependencies:

• glob ^14.0.3: workbox-build 7.4.1 (the latest 7.x) uses glob 11, which is deprecated and vulnerable;
• minimatch ^11.0.4: fixes the glob-pattern DoS (GHSA-g3hv-75wg-m249) in eslint, typescript-eslint and workbox-build.

If an update of eslint, typescript-eslint or workbox-build starts requiring a different version of either, remove the override and run npm run check and npm run build.

Accepted risk: deepmerge 4.3.1 (prototype pollution in mergeObject(), low severity, GHSA-gcqx-w48m-w2h4), used by @rollup/plugin-node-resolve inside workbox-build and vite-plugin-pwa. There is no fixed version (4.3.1 is the latest), and it only merges the build options, which are ours. That is why npm audit still shows 4 low-severity vulnerabilities (deepmerge and the three packages that depend on it). Reassess when workbox-build switches dependencies.

Structure

index.html              page (Vite entry point)
settings.json           site configuration (default Bible)
src/
  core/                 pure logic: EBF1 format, references, rendering, search, XML
  data/                 loading of the index and of the Bibles
  router/               SPA router (History API), independent of the screens
  screens/              screens; reader/ is the reading one (/{bible}/{book}/{passage})
  ui/                   theme, modals, messages, preferences
  sw/                   service worker (Workbox)
  app.ts                registration of the screens and routes
public/                 copied unchanged into the build
  assets/data/          Bibles (*.ebf1.json) and the index.json generated at build time
  assets/icons/
  manifest.json
scripts/                build-index.ts (generates index.json) and check-dist.mjs
tests/                  unit tests (Vitest)
e2e/                    end-to-end tests (Playwright)

Bibles

The Bibles live in public/assets/data/bibles in the Easy Bible Format (EBF1) and are published exactly as they are in the repository, so that they can be downloaded and used in other projects:

• the tests validate all of them against the official schema (ebf1-schema.json), which comes from the format's repository as an npm dependency pinned to a commit (easy-bible-format in package.json). To update the schema, change the commit hash and run npm install;
• scripts/check-dist.mjs runs at the end of every build and fails if any published file differs from its source.

To add a Bible, just drop the .ebf1.json file into public/assets/data/bibles. The index (public/assets/data/index.json, not in git) is generated by scripts/build-index.ts on every npm run build and npm run dev: name, type (Catholic/Protestant, by the number of books), language (ISO 639-3) and URL slug, all taken from the file name (por_ave_maria.ebf1.json → /por/ave-maria, which opens at /por/ave-maria/jo/3,16). The file name must start with the language. The build fails if a name is repeated or if a slug is repeated within the same language.

The Bible opened on the first visit is set in settings.json, by language and slug:

{
    "defaultBible": "por/ave-maria"
}