PROJECT HAS MOVED HERE: https://gitlab.com/dwep-app/dwep-app.gitlab.io

DWEP - Daily Wellness Empowerment Program

About the project: https://codeberg.org/tord/dwep/wiki/Home

Live page, showing the latest development: https://tord.codeberg.page/dwep/

Credits/Thanks/License: Please see "Menu" -> "About" inside the app

This readme file is primarily for developers and is not available inside the app itself

Browser and OS support

This app should work on all major browsers and operating systems, both for mobile and desktop. Javascript is required for the application to run, so the browser needs to support that and cannot block Javascript (for example using a plugin/extension). We expect most people will want to run the application on mobile so the layout has been designed for vertical screens

The browser support is tested (at the time of writing) by running auto-test on desktop with playwright, which runs test using three browser engines - Blink (Chrome, Edge), Gecko (Firefox), WebKit (Safari, Gnome Web) - which in playwright are called "chromium", "firefox", "webkit". Playwright also emulates mobile devices ('Mobile Chrome', 'Mobile Safari'), and this emulation includes platform-specific features

Development setup

Dev dependencies

To install all the dev dependencies in the package.json file you can run this command: npm install. (The app itself doesn't have any dependencies at the time of writing)

eslint is also available as a vscode extension

Git hooks

Run git config core.hooksPath ./dev/git-hooks/ to configure git to use our git-hooks. They will run auto-tests and do some work with the version. For details please see the git-hook files

We rely on Unix-system and bash commands in our git-hook files, so you need something like Ubuntu, MacOS (or if you are running on Windows maybe Cygwin or similar)

Versioning and Caching

Please remember to update the version in package.json before making any changes you want the user to see

Because of how caching is done in our service worker you need to update the app version for any changes to be shown. The central/master version is stored in package.json, and when a commit is done the version string is copied into other files (using the precommit hook)

An alternative way to ensure you are seeing the latest version is to keep doing hard reloads since this will bypass the caching system we have implemented (this can be useful during development)

For more info about the caching strategy please see service-worker.js

Local development server

Below two local dev server options are discussed. Both require a certificate to work

To generate certificate files, mkcert can be used

• Links:
  • https://mkcert.org/
  • https://github.com/FiloSottile/mkcert
• Installation on Ubuntu:
  • sudo apt install mkcert
  • sudo apt install libnss3-tools (to get certutil)
• mkcert -install
• In the project base dir: mkcert localhost (generates two files: localhost.pem, localhost-key.pem)

http-server

This is used in the script section in package.json, and therefore also by the git-hook scripts

To start the server the certificate files can be given on the command line. (See the script section in package.json)

URL: https://localhost:3001/

VSCode Liveserver extension

Configure the vscode liveserver extension (in the global settings.json file). See below for the configuration (not version controlled). You will have to replace the paths to match your system

"liveServer.settings.https": {
 "enable": true,
 "cert": "/home/sunyata/DevProjects/dwep/localhost.pem",
 "key": "/home/sunyata/DevProjects/dwep/localhost-key.pem",
 "passphrase": ""
}

URL: https://localhost:3000/

Debugging options

• Desktop -> Chrome on Android
  • Guide: https://developer.chrome.com/docs/devtools/remote-debugging
  • Note: It seems like chrome://inspect/#devices has to be open
• Desktop Chrome through http-server (or liveserver)
  • Start local server
    • http-server: npm run start-server
    • vscode liveserver: click "Go Live" in lower-right corner
  • Go to the url (if not already open)
  • Chrome devtools settings:
    • Console tab -> Settings -> Preserve log
    • Application tab -> Service workers -> Update on reload (If we don't have this we either need to make a "hard reload", ctrl+shift+r, or update the app version in package.json)
• Desktop Firefox through liveserver
• Desktop Firefox directly through index.html

Workflow

Branches:

• development --- This is where we work
• main --- changes to this branch are reflected in our live page https://tord.codeberg.page/dwep/

1. switch to the development branch
2. make changes
3. Before merging any branch into main, please remember to update the version in package.json --- if you forget this you will get a reminder from the pre-merge-commit
4. switch to the main branch
5. git merge development
6. git push
7. the changes will be visible on https://tord.codeberg.page/dwep/ --- you may need to do a soft reload or even two

Testing

Auto-tests

Playwright is used for auto-testing

To run tests in the terminal: npm run test

To run tests in the Playwright GUI: npm run test-visual

To generate tests using Playwright codegen: npm run test-codegen

By default tests will run in multiple emulated browsers. Playwright's Firefox has been configured to ignore https errors (see playwright.config.js), but not Playwright's Chromium. The reason is that Chromium uses the certificate store from the OS, while Firefox uses it's own, and it's difficult to configure this in Firefox

Manual tests

Test procedures to be carried out manually by developers are kept at the bottom of the test file (tests/main.spec.js), and are intended to complement the auto-tests by testing things which cannot be covered by Playwright

Technical notes

We use relative instead of absolute paths (./ rather than /dwep/) for the app, which works without issue.

Please note that the path in the start_url in dwep.webmanifest doesn't have index.html in it. In general index.html will not work (in general, not just for installed PWA) because of a redirect+security issue around caching (that i don't understand). I thought it best to simply not use index.html since it's not needed. (However there is a possible solution discussed here)

Hard and soft/normal reload when debugging: TODO A hard reload will bypass the fetch event handler

Update of version for cache reasons: TODO

You can find more tech notes in the code files

Problems and solutions

Unregistering the service worker might help in some cases

Failed to fetch index.html (ERR_FAILED)

Solution: Rewrote the fetch handler

Hosting/Server

We use Codeberg for the hosting. Since we use a cache-first strategy the app shouldn't put a lot of load on the server

The server status can be seen here: https://status.codeberg.org/status/codeberg

There's a delay of maybe 5 minutes after pushing new changes to main/origin

PostHog telemetry/analytics

TBD

Please use an adblocker for the development users so they don't effect the stats that we see in PostHog

Please note that there is some delay in the posthog interface

• Even just when looking at the activity there's about 30-60 seconds delay. To update use the "Reload" button inside of the page, rather than the browser reload
• _

Translations and localization

The plan is to have all language-specific texts in the index.html file, using the lang attribute on the html tag. In the future (if the number of languages grows) we might move to a separate json file for each language.

We store dates in this format: 2025年01月05日 (year-month-day)

Technical strategy and reasoning

Maintainability is prio

SPA, no build-tools, plain JS

Choice of PWA (Progressive Web App) over other options

In short, we choose PWA rather than using native apps because we need something that can be run on both Android, iOS and desktop platforms

Choice of local only (no server-side code)

This is to reduce complexity (which in turn reduces the development time, increases maintainability, and makes bugs easier to fix since we have more control)

Choice of cache-first (see service-worker.js)

This was an easy choice. It makes it easy to run the PWA when offline (which people in plumvillage may be), and to reduce the load on the server (makes it possible to run the app from a low-performance server). (I don't see any downsides)

Choice of using few or no frameworks, libs and external connections

This is to reduce complexity, and make the app more future-safe (frameworks may change, bug plain JavaScript will be supported for a long time)