xinjs app boilerplate

Get Up and Running

You will need nodejs and bun. Exactly version should not be important, but if you run into problems maybe upgrade?

You'll also need to install the firebase admin (globally).

1. Create a folder (e.g. nonono)
2. Create your secrets file and put it in a subfolder as secrets/firebase-secrets.json
   1. Firebase Console
   2. Project Overview (gear, top-leftish)
   3. Service Accounts (tab)
   4. Generate New Private Key (button at bottom)
   5. Find that file, rename it "firebase-secrets" and stick it in /secrets
   6. You'll need to run firebase login (and possibly preceded by firebase logout) see this question on Stack Overflow
3. Clone the repo into the nonono folder (name doesn't matter, but nonono-pwa-firebase is the default) So, now you have a nonono directory with two subfolders, secrets and nonono-pwa-firebase (or whatever) And the secrets folder contains a json file named firebase-secrets.json and the other folder is a clone of the project repo which, notably, contains a ./functions subfolder. OK?
4. inside the the project folder (nonono-pwa-firebase or whatever) npm install
5. (inside ./functions) npm install // this is a separate project with its own dependencies
6. bun install // bun stores its own highly optimized binary dependency tree
7. in one terminal npm run emulators // ctrl-c then reset emulators to stop them later
8. in a second terminal npm run dev // ctrl-c to kill this later

You may also need to run this command:

firebase functions:secrets:access --project <PROJECT_ID> <NAME_OF_SCECRET>

E.g.

firebase functions:secrets:access --project 171481538073 stripe-nonono-test

After doing this, be sure to restart your emulators.

Troubleshooting

• If you can't do step 2, don't panic, you probably need to be added to the project by a project admin.
• If you can't install bun, what can I say? stop using Windows or use the Linux subsystem or something.
• If you have another problem then complain to someone and make sure it gets fixed and documented :D

The site should load on http://localhost:1234

By default, the app will use emulated services on localhost unless you add #prod to the url and reload (in which case it will use production). You can skip step 5 if you want to use prod

FireBase Emulators

To emulate services locally, in a separate terminal:

1. npm run reset-emulators (if you've been runing them earlier)
2. npm run emulators

If you're running locally and try to log in using a phone number, the confirmation code will be displayed in the terminal running the emulators.

Installing / Upgrading firebase-tools

Apparently the npm package is deprecated so to sort issues with zany bugs in firebase-tools you need to do this.

If necessary:

  npm uninstall -g firebase-tools

Then:

  curl -sL https://firebase.tools | bash

firebase-config.ts

../secrets/...admin

1. Firebase > Project Settings > Sevice accounts
2. Generate new private key
3. Move resulting file to ../secrets directory outside the project root

Note that the project id in the deploy command must match that in the credentials JSON

You will need to go to the App Engine console to create an App Engine instance if you haven't already.

firebase emulator firestore.rules bug

It looks like the way to really fix this is:

1. completely uninstall firebase-tools, e.g. sudo npm uninstall -g firebase-tools or curl -sL firebase.tools | uninstall=true bash
2. reinstall it
3. rm -rf ~/.cache/firebase (this forces new emulator binaries to be downloaded)

Also note, this may entail upgrading Java.

Useful Document Links

• High Level Design

TODO

• cloud function example
• non-trivial service example
• utility functions for saving and recovering binaries in storage
• type-checking