Repository navigation
Development
How to set up LibreBars and run what there is of it. This file grows with the repository: each app gets its section in the pull request that adds it.
- Node 26 (see
.nvmrc) and pnpm 12. - For iOS: Xcode with an iOS simulator, and CocoaPods.
- For Android: the Android SDK with an emulator, and Java 17.
The web version of the app and the tests need only Node and pnpm. Running the API also needs Docker.
pnpm installThe workspace holds back packages that were published very recently. If an install refuses a package for that reason, wait or pick an older version; don't switch the hold off.
pnpm check # everything the check job in CI runs
pnpm test # unit tests, in every package
pnpm typecheck # TypeScript, in every package
pnpm lint # Biome
pnpm format # Biome, fixing what it canpnpm check is the one command to run before saying a change is done. It is a script in the
root package.json, and a step is added to it when the thing it checks exists.
Biome does not check Markdown. It is left out because the formatter breaks the front matter of the decision records.
The app is in apps/app. It is an iOS and Android app. Its web build stays until the app is
in the stores (0007), so it has to keep working, and
pnpm check builds it. It has the workout loop: routines, a workout in progress, history and
settings, and it backs the log up to the API when one is running.
pnpm app ios # build and run in the iOS simulator
pnpm app android # build and run in an Android emulator
pnpm app web # the web build, on http://localhost:8081
pnpm app export:web # export the web build into apps/app/dist
pnpm app test # the database and its functions, on Node
pnpm app db:generate # write a migration after changing src/db/schema.tsThe app keeps its data in SQLite through expo-sqlite, with Drizzle
(0018, 0024).
- The tables are in
apps/app/src/db/schema.ts. After changing them, runpnpm app db:generate --name <what-changed>and commit the new folder inapps/app/drizzlewith the change. The app runs every migration it has not yet run when it starts. - A synced table is only ever changed through the functions in
src/db/synced.ts, which write the outbox note in the same transaction. Several rows of one table go in with oneinsertSyncedMany. -
expo-sqlitecarries a patch frompatches/, for the web build (0022). pnpm applies it on install. - The tests run on Node's own SQLite against the same migrations, so they need no phone.
- After adding a Tailwind class the app has not used before, restart the dev server. The browser picks new classes up at once; the phone's styles are only built when it starts.
- The web build only works on a page served with
Cross-Origin-Embedder-Policy: credentiallessandCross-Origin-Opener-Policy: same-origin. The dev server sends them. A host for the exported build has to send them too. Only one tab can have the app open; a second one says so and leaves the database alone.
The native projects in apps/app/ios and apps/app/android are generated by the build and
are not committed. Change native settings in apps/app/app.json, not in those folders.
pod install can crash with "Unicode Normalization not appropriate for ASCII-8BIT" when the
shell has no UTF-8 locale. Set one and run the build again:
export LANG=en_US.UTF-8A debug build loads its code from the dev server on your machine. Forward the port to the emulator, then reopen the app:
adb reverse tcp:8081 tcp:8081apps/web is the website, librebars.app: for now a home page and a placeholder for the account, later also
the docs, the blog, the exercise catalog and the account dashboard. It is a TanStack Start app
that is built into static files (0025). It is built and
checked by pnpm check, and published from main to GitHub Pages.
pnpm web dev # http://localhost:3000
pnpm web build # build into apps/web/dist/client and check the result
pnpm web preview # serve the build the way GitHub Pages does, on http://localhost:4322
pnpm web icons # regenerate the favicon, icons and social image from the logo mark- The build fails if a page loads something from another origin or a link on it doesn't resolve.
- The site's name, address and links are in
apps/web/src/lib/site.ts. It is published at librebars.app, at the root, which is what a plain build is for. - To build it for another address, such as a fork's
https://<you>.github.io/librebars, setVITE_SITE_URLto that address andVITE_SITE_BASEto its path (/librebars/) forpnpm web build, and the second forpnpm web preview. - After adding a route, build once before running the typecheck, so that the generated route tree knows it.
-
apps/web/AGENTS.mdhas the rules for working on it, the first of which is that the site says only what is true today.
Not to be confused with pnpm app web, which runs the web build of the app.
apps/api is a Fastify service (0015) on Postgres 18
(0021). Node runs its TypeScript directly, so there is
nothing to build. It needs Docker for its database. It has guest accounts and sync.
The first time:
cp apps/api/.env.example apps/api/.env # then put a secret in AUTH_SECRET, as the file says
pnpm api db:up # start Postgres in Docker
pnpm api db:migrate # create its tablesAfter that:
pnpm api db:up # start Postgres, if it is not running
pnpm api dev # http://localhost:3002, restarts on change
pnpm api test # on an in-process Postgres; nothing needs to be running
pnpm api db:down # stop Postgres; its data is kept- The ports are 3002 for the API and 5433 for Postgres, one above LibreLifts', so that both projects can run on one machine.
- The tables are in
apps/api/src/db/schema. After changing them, runpnpm api db:generate --name <what-changed>, commit the new folder inapps/api/drizzle, and runpnpm api db:migrate. - To run the tests on the real Postgres, as CI does, set
TEST_DATABASE_URLto theDATABASE_URLin.env.example. Each test file gets a database of its own and removes it afterwards. - Accounts are Better Auth's (0017). Its routes are under
/api/auth, andGET /accountsays who is signed in. - The app looks for the API at
http://localhost:3002. SetEXPO_PUBLIC_API_URLto point it elsewhere. An Android emulator reaches this machine withadb reverse tcp:3002 tcp:3002. - Sync is
POST /sync/pushandGET /sync/pull(0019). The shapes are inpackages/contracts. When a synced table changes on the device, change its twin inapps/api/src/db/schema/personal.ts, the shape inpackages/contracts, and raiseschemaVersionthere. Tests on both sides compare the tables with the contract. - With the API running, the app gets itself a guest account (0016) and, once the first-launch notice is answered, backs up. Settings in the app says what backup is doing.
- To see a restore in the web build: open
http://localhost:8081/favicon.ico, which is the same origin without the app running, remove theexpo-sqlitefolder from the origin's private file system in the console, and open the app again. The session cookie is still there, so the log comes back from the server.
Four packages hold what more than one app needs. Each is plain TypeScript source with no build step, and none imports another.
| Package | What to know |
|---|---|
packages/engine |
One function per file with its test beside it. No dependencies, nothing impure. |
packages/ui |
src/theme.css is the only place a colour is defined. |
packages/data |
The exercises. An id is permanent: never change or reuse one. |
packages/contracts |
The API's shapes, and the synced tables: their order, columns and version. |
To run one package's tests: pnpm --filter @librebars/engine test.
Docs are plain Markdown in docs/. Links between them are relative paths to the .md file,
so they work on GitHub and can be rewritten for the wiki.
The wiki is built from docs/ by scripts/wiki.ts. To see what will be published:
pnpm wiki # writes the wiki pages to dist/wikiIt fails if a link between docs doesn't resolve, and it is a step of pnpm check.
Generated from docs/ on dev. Edit the docs there; changes made on the wiki are overwritten.
- Development
- Workflow
-
Decisions
- 0001 Decisions are recorded
- 0002 Apache License 2.0
- 0003 Changes land on dev by fast-forward; main is the last release
- 0004 Conventional Commits, Keep a Changelog and Semantic Versioning
- 0005 docs/ is for developers and is mirrored to the wiki
- 0006 LibreBars is a free workout log for calisthenics
- 0007 The tracker is an iOS and Android app; its web build stays until the store release
- 0008 LibreBars is an app and a crowd-sourced open database
- 0009 The database is ODbL, media is CC BY-SA, and neither can be closed later
- 0010 A hosted API with a free tier is the paid product
- 0011 The workspace is app, web and api, with engine, ui, data and contracts
- 0012 The engine is small pure functions, in the style of date-fns
- 0013 Web and app share a Tailwind theme, not components
- 0014 Postgres is the source of truth for all data
- 0015 The API is Fastify, and it owns LibreBars accounts
- 0016 Every install is a guest account, made in the background
- 0017 Accounts use Better Auth
- 0018 The on-device database is SQLite with Drizzle, on every platform
- 0019 Sync is our own push and pull
- 0020 The app says it backs up, and backup can be turned off
- 0021 Postgres 18, run with Docker Compose and tested on two databases
- 0022 expo-sqlite is patched so the web build reuses one buffer
- 0023 Seed data is TypeScript modules in packages/data, with permanent ids
- 0024 The first tables
- 0025 One TanStack Start app is the website, on GitHub Pages
- 0026 The catalog reaches the app as a snapshot plus updates, and the website through the API
- 0027 The app's first components are its own