appbuilder-pwa

A template for building a Progressive Web App with Scripture App Builder.

Prerequisites

• Visual Studio Code
• Node 20.9.0+ (we recommend using Volta to manage the Node versions)

Usage

You will need to download the latest version of Scripture App Builder to use this project without the provided example data.

Develop

Install dependencies with npm install.

The PWA depends on data files generated by Scripture App Builder. There is example data provided in the repo. To convert the base data files and run the PWA, do one of the following:

Example Data

• Run npm run extract:example <project_name> to generate data from projects in the test_data/projects. For example, web_gospels is an SAB project name and hanga is a DAB project name. Note, this requires java to either be on the path, or to have a JAVA_HOME env variable.
• Run npm run dev to start the development server.

Scripture App Builder Project

• Run Build PWA Data Files in Scripture App Builder to generate the the base data files from a project
• Run npm run dev to convert the base data files to a format needed for the PWA and run the development server. Changes to the base database files are watched and applied to the running PWA.

Contact chris_hubbard@sil.org for the feature key to enable Build PWA Data Files

Note: The book conversion step can take up to several minutes depending on the amount of scripture in the project and the speed of your computer's hard drive.

Build

Run npm run build to build an app with the data provided by Build PWA Data Files.

Run npm run build:examples to build an app with the example data.

The production build can be viewed by running npm run preview. The production build can be deployed to a public webserver for testing using Surge.

Running on Device

While npm run dev or npm run preview is running, type d and press Enter to open the app in the default browser of an Android device connected over USB.

This uses adb reverse to forward the device's port to your computer. The app then loads from http://localhost rather than from your computer's network address. Browsers treat localhost as a secure context, so service workers and other PWA features work without setting up HTTPS. The forward is removed when the server stops.

Run npm run preview:device instead of npm run preview to open the production build on the device as soon as the server starts. It opens only when exactly one device is connected (or the one set by ANDROID_SERIAL, see below). Otherwise it logs why it didn't, and the server runs as usual. Setting the OPEN_ON_DEVICE environment variable does the same for npm run preview.

Setup

• Install the Android SDK Platform Tools, which provide adb. They come with Android Studio or the Android SDK used by Scripture App Builder, or you can download them separately.
• On the device, enable Developer options and turn on USB debugging. Connect the device and accept the "Allow USB debugging?" prompt.
• Run adb devices to check that the device is listed as device rather than unauthorized.

adb is looked for in this order:

1. The ADB environment variable, set to the full path of the adb executable
2. $ANDROID_HOME/platform-tools
3. $ANDROID_SDK_ROOT/platform-tools
4. The PATH

If adb isn't found, the error message says what to set.

Multiple Devices

If more than one device or emulator is connected, set ANDROID_SERIAL to the serial number of the one to use, as shown by adb devices:

ANDROID_SERIAL=<serial> npm run dev

On Windows, run set ANDROID_SERIAL=<serial> (Command Prompt) or $env:ANDROID_SERIAL="<serial>" (PowerShell) before npm run dev.

Use chrome://inspect in Chrome on your computer to open DevTools for the page running on the device.

Testing

Scripture App Builder PWA uses Vitest for unit tests. See that added test files and tests adhere to the Front End Testing Style Guide.

├── scripts
│   ├── scripture-reference-utils.test.ts
│   └── scripture-reference-utils.ts

Run npm test to run created test files.

Deployment

This project is configured by default with the static adaptor, which will allow deployment on any platform that requires a static site.

Data Sandbox

The project uses Proskomma (docs) which is a JavaScript Scripture Runtime Engine for reading USFM. It provides a GraphQL interface to the data.

It is useful to be able to directly query the data during development. The data-sandbox sub-project is a conversion of diegesis-apollo-sandbox to use the data generated by the convert sub-project for the PWA.

After you have run Build PWA Data Files from Scripture App Builder to populate files in the /data directory, then run these commands.

npm install
npm run convert
cd data-sandbox
npm install
cd ..
npm run sandbox

Open a browser to http://localhost:2468/graphql to query the Scripture data using GraphQL.

Release

The version of the PWA can be read from the property version from the file _app/version.json. AppBuilders includes the latest tagged version of the repo. Before making a new release with the AppBuilders, do the following:

• update the version in package.json with the version of the AppBuilders
• merge into main
• tag main with "v{version}"