Welcome To My Garden

This repository houses the entire Welcome To My Garden app.

Contributing

Use Discussions to discuss feature requests, ideas and questions regarding WTMG. We're also on our Slack.

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

We use the package manager Yarn, install it if you haven't already.
Ensure you have Node 16 installed. Use nvm if needed. Any version >= 14 should work too, but we are using 16 for development.
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 globally.
```
yarn global add firebase-tools
```
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

cp .env.example .env

# 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:

access your local WTMG app at http://127.0.0.1:5173/
access the Firebase emulator dashboard UI should be http://127.0.0.1:4001/

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:

Creating an account
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).
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:

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

What can you NOT immediately do?

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

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

After running yarn install, also install the testing browsers:

npx playwright install

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

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.

thdk / welcometomygarden