Skip to content

Latest commit

 

History

History
159 lines (96 loc) · 9.2 KB

README.md

File metadata and controls

159 lines (96 loc) · 9.2 KB
Raw

Welcome To My Garden GitHub Translation status

This repository houses the entire Welcome To My Garden app.

Contributing

Use Discussions to discuss feature requests, ideas and questions regarding WTMG.

Problems & bug reports are welcome in Issues.

If you want to contribute to the code, read on!

Get started coding

WTMG has a frontend built with SvelteKit, and a backend largely on built on Firebase (see also /api). Several functions also depend on SendGrid (email), and Stripe (subscriptions for our Superfan program).

Firebase is not our dream ecosystem, but it has supported WTMG's growth uptil now, and is easier to manage for our tiny team of contributors. We might migrate to another system later.

First, set up your dev environment

  • Ensure you have Node v20 installed. Using nvm is recommended. At the time of writing, you need v20.11.0 specifically to prevent a https issue in the dev server. The project probably works with v18 still, and might work with other older or newer versions too, but these aren't tested.

  • Ensure you have Java >= v11 is installed, preferably the latest LTS version (17). This is required for Firebase's CLI. Adoptium builds are helpful.

  • Install the Firebase CLI and Yarn globally. The global npm Yarn install will install a v1 ("Classic") version, but this version will replace itself with a locked version checked into this repository (3.5.0 at the time of writing) using the .yarnrc.yml configuration:

    npm i -g firebase-tools yarn

  • Install project dependencies, in both the root and /api directory.

    yarn
cd api && yarn

  • Create environment files from their examples.

    # For the frontend SvelteKit app
# This follows the way Vite env files are set up: https://vitejs.dev/guide/env-and-mode.html#modes

cp .env.example .env.development.local

# Create a .runtimeconfig.json file in /api, for Firebase Cloud Functions

cp api/.runtimeconfig-example.json api/.runtimeconfig.json

Next, get the dev servers running

Start all Firebase emulators:

yarn firebase:demo

This will locally emulate our "backend": Firebase's Auth, Firestore, Storage, Hosting and Cloud Functions modules.

In a new terminal, run:

yarn dev

This will run a SvelteKit app dev server via Vite (our frontend). SvelteKit also has server-side (backend) capabilities, but for the moment we use it as a pure frontend static site generator via adapter-static.

If you use VSCode (recommended), you can also execute both commands at the same time using the pre-configured Run Build Task command.

There are several other development scripts available in package.json, for example, yarn firebase:demo-seed will add some testing data to the dev env upon startup.

What can you do now?

Assuming that you did the above, you now have a partially functioning development environment!

You should now be able to:

If this doesn't work, check your web console logs if your ad blocker is enabled and blocking certain code modules from loading in the development watcher of Vite. Disable the ad blocker on your localhost:5173, or add exception rules.

In the app, you can now try:

  1. Creating an account
  2. Since you don't have access to the SendGrid variables, no emails will be sent. You can see what emails would have been sent in the Firebase Emulator logs terminal (e.g. to access your email verification link).
  3. You can add a test garden and also upload a file into emulated Storage (but because of this bug their images won't show up).

⚠️ Importantly, with the default demo development environment, the map will be empty/broken by default. That's because you're missing an API token. If you get your own Mapbox Access Token and fill it in in .env, most basic features of the map should work. You may need to restart the Vite server. Mapbox asks for payment details to get a token, but has a free tier that should be sufficient for your local development needs. If you really dislike this, upvote the issue to support an open & free alternative.

Some features are reserved for Superfans. You can make your local test account a Superfan easily (and without Stripe) by:

  1. Opening the Firestore emulator dashboard, the users collection (http://localhost:4001/firestore/data/users)
  2. Going to your test account's document (as a title, it has your user ID)
  3. Adding a boolean field named superfan, setting it to true.

What can you NOT immediately do?

  • Some static images will be missing. We started dynamically generating responsive images on build-time for some newer components, rather than using one-size static images hosted in a bucket. The source images for this process should be put in src/lib/assets, but are not checked into the Git repo. You can download this Google Drive and manually drop the contents in the mentioned local folder. See the additional notes if you have full access to WTMG's systems to learn about syncing this folder.
  • Preview the email HTML, and test contact property syncing functionality - except if you create your own SendGrid account. It's a quick procedure to set up your own free account for testing.
  • Work on subscription features - except if you go through the hassle of setting up your own test company on Stripe!
  • Log into the Discourse community reserved for Superfans - except if you set up your own Discourse server for testing, see additional Discourse notes

If you have received access to our staging or production Firebase environment, see how to log in your Firebase account & access real API services with these additional notes.

Code orientation

The architecture docs contain some notes on the architecture of the app.

Testing

Backend unit & integration tests

There are some backend unit and integration tests. The test running procedure is described in ./api/README.md -> "Running tests".

Front-end unit & Firestore rules tests

Some firestore rules unit tests live in ./tests/unit/firestore-rules.test.ts. To run them from the root directory:

cd api && echo 'cd .. && yarn test:unit' > runtests.sh && firebase --project demo-test emulators:exec --ui --only auth,firestore ./runtests.sh; cd -

E2E tests

Playwright is set up for e2e testing, but does not contain any tests at the moment.

After running yarn install, also install the testing browsers:

npx playwright install

Production builds

To check if your code won't have compilation issues in production, do a production build locally and preview the result:

yarn build:prod
yarn preview

You will need the right environment variables for this.

Deployment

Gitub Actions are set up for a production environment (based off master), a beta environment (beta) and a staging environment (staging). These only deploy the SvelteKit frontend, and not the Cloud Functions in /api. See /api to learn how the backend functions are deployed.

The beta environment connects to the production Firebase backend, but has an independent frontend.

The staging environment connects to a separate staging Firebase backend.

Translations

The website is translated through Hosted Weblate. You can easily make an account and start translating in their web-environment - no installation required.

Translation status

License

GitHub