basis-scheme-assets

Scheme-specific image assets for the Beryl rider app (non-white-label / sponsored schemes such as West Midlands, Leeds, Greater Manchester, etc.).

Images live here as source @3x PNGs. On release, CI generates @1x/@2x variants, uploads every resolution to a Google Cloud Storage bucket, and publishes an npm package (@weareberyl/scheme-assets) whose scheme_assets.json maps each image name to its hosted URI and dimensions. The mobile app then bumps the package version to pick up the new images.

For adding images directly to the mobile app bundle (white-label / shared images), see add_new_images.md in the basis-mobile repo. This repo is only for scheme images.

How it works

• Only the @3x PNG is stored in version control, under assets/<scheme>/<image_name>.png.
• codegen-sizes reads each @3x image, divides its width/height by 3, and writes package/scheme_assets.json — keyed by <scheme> → <image_name> (filename without .png) → { uri, width, height, aspectRatio }. The uri points at the GCloud bucket under the release tag.
• resize-images regenerates the @1x and @2x images (and copies the @3x) into output/.
• gcloud-sync uploads everything in output/ to gs://beryl-basis-production-rider-app-images/<tag>/<scheme>/....
• publish publishes the npm package at version <tag>.

These last steps all run in CI (CircleCI) — you do not run them locally.

Adding a new image

1. Create the @3x PNG at the correct dimensions. Only the @3x is committed; @1x and @2x are generated automatically in CI, so do not commit them.

2. Place it in the scheme folder: assets/<scheme>/<image_name>.png.

   • Use an existing scheme folder (e.g. assets/greater-manchester/) or create a new one named after the scheme.
   • Follow the naming convention for the scheme — image names are prefixed by the scheme abbreviation, e.g. wm_ (West Midlands), leeds_, gm_ (Greater Manchester). The filename (minus .png) becomes the key the mobile app references, so match the names the app expects.
   • Use underscores, not dashes, in the filename. Android drawable resource names can't contain dashes (-), so a file like gm-training.png will break the Android build. Use gm_training.png instead. (Scheme folder names like greater-manchester may use dashes — this only applies to the image filename.)

3. Compress the image:

   git add assets/<scheme>/<image_name>.png
   yarn compress-images
   git add assets/<scheme>/<image_name>.png   # re-add after compression

   compress-images runs oxipng over staged PNGs. CI runs yarn is-compressed and fails the build if any image isn't already compressed, so this step is required before pushing.

4. Commit, push, and open a PR against master. Get it reviewed and merged.

5. Release it by pushing a git tag (this is what triggers the GCloud upload and npm publish — merging alone does nothing):

   • Release candidate (testing from a feature branch, before merge): tag with a pre-release version, e.g. 0.42.0-rc.1. CI rejects non-rc tags on feature branches and rc tags on master.
   • Production release (from master): tag with a plain semver, e.g. 0.42.0.

   On a matching tag, CI runs build → sync-gcloud → publish, uploading the images to the bucket under the tag name and publishing @weareberyl/scheme-assets@<tag>.

   If the publish step fails, it's most likely an expired NPM token. Publishing to NPM uses an NPM_TOKEN set on CircleCI (in the beryl-basis-global context), generated by the basis-machine-user NPM account. This token expires every 90 days, so when a publish that previously worked starts failing on auth, the fix is to log in as basis-machine-user, generate a fresh NPM token, and update the NPM_TOKEN value in CircleCI.

6. Update the mobile app: bump the @weareberyl/scheme-assets dependency to the newly published version. The new image is then available via the generated scheme_assets.json.

Local commands

| Command | What it does | | --- | --- | | yarn compress-images | Compress staged PNGs with oxipng (run before committing). | | yarn is-compressed | Verify staged PNGs are already compressed (CI gate). | | yarn codegen-sizes --tag <tag> | Generate package/scheme_assets.json + index.ts. | | yarn resize-images | Generate @1x/@2x images into output/. | | yarn gcloud-sync --tag <tag> | Upload output/ to the GCloud bucket (needs auth). | | yarn build | Compile the package to build/. |

codegen-sizes, resize-images, gcloud-sync, and publish normally run only in CI on a tagged build — you rarely need to run them by hand.