Skip to main content

Setup

Compass is a monorepo that contains everything needed to get a calendar app up and running, including frontend, backend, database, and dev scripts.

By the end of this guide, you'll have a local development environment that has:

  1. a running NodeJS API server, which'll hot-reload upon changes
  2. a running React web app, which'll also hot-reload upon changes
  3. a MongoDB instance with your calendar data
  4. a CLI, which you can use to create a distributable artifact
  5. package.json scripts to run local tests

You'll then be ready to play with the local web app and test any changes you'd like to make.

Ready? Let's go!

Get the Code​

  1. Clone the repo:

    git clone https://github.com/SwitchbackTech/compass.git

    cd compass

Setup the .env files​

This is the file that contains your custom and sensitive information. We're creating the file now so we can update the values as we set up our third-party accounts.

  1. Copy compass/packages/backend/.env.local.example and save as compass/packages/backend/.env.local.
  2. Read through the comments to familiarize yourself with the environment variables.
  3. If you plan on deploying Compass to a production environment, also create .env.staging and .env.production for further separation of environments.

Setup Accounts​

Compass relies on a few external services. Let's start by creating accounts for those and adding the credentials to that environment file.

Google OAuth​

Compass uses the Google Calendar API to import and sync events from GCal.

Google APIs require authentication through OAuth.

To use Google OAuth, create a Google Cloud Platform project and setup an OAuth screen.

  1. Create a Google Cloud account
  2. Create a project
  3. Configure your OAuth consent screen for internal testing
    • Set the User type to External and status to Testing
    • Add your test Google accounts to the list of authorized users
    • You don't have to manually add scopes -- the Compass code does that for you (Login.tsx)
  4. Get Google API Client ID & Secret
    • Go to Credentials in your Google Cloud project
    • Create an OAuth Client ID
    • Select Web Application
    • Add to Authorized JavaScript origins: http://localhost:9080
    • Add to Authorized redirect URIs: http://localhost:3000
    • Copy the Client ID and Secret to your .env.local file
  5. Enable the Google Calendar API in your GCP project
    • Navigate to the API Library in your Google Cloud project
    • Use the search bar at the top of the page to search for "Google Calendar API"
    • Click on "Google Calendar API" from the search results
    • Click the "Enable" button to activate the API for your project
    • Wait for the API to be enabled (this usually takes a few seconds)
    • Once enabled, you'll see a confirmation message and can verify the API is active by checking the Enabled APIs page

MongoDB​

MongoDB Overview​

Before using Mongo db, ensure you create a free MongoDB Atlas account that allows you to create a Mongo db database, which is the easiest and quickest way to get started with Mongo without needing to install it locally.

User data is stored across a few MongoDB collections. These collections are created automatically at runtime, so you just have to create an account to get started.

Instructions​

Compass connects to MongoDB through the NodeJS driver.

  1. Create a free MongoDB Atlas account
  2. Get your Node.js driver connection string
  3. When you get your connection string, scroll down to the Network access in the left sidebar and add your current ip address. Make sure you always include your ip address when you switch networks because your device ip v4 address changes from one ISP to another and from time to time.
  4. Add connection string to your .env.local file
  5. Recommended: Install MongoDB Compass desktop app to visually inspect and manage your database during local development. You can connect to your MongoDB Atlas instance using the same connection string from your .env file.

Supertokens​

Supertokens Overview​

Compass uses Supertokens to manage user sessions. This is what allows users to stay signed in between page refreshes. It also prompts reauthorization after an extended time away.

Supertokens offers many different authentication options. Compass only uses their managed session service, which means you don't have to worry about a lot of their onboarding. What we do need is to get the credentials to Supertokens Core, their managed-service.

Supertokens will provision the auth infrastructure in AWS for you, presenting a connection URI and API key afterwards. That's all we need to get started.

Supertokens Instructions​

  1. Create a free Supertokens account
  2. Click trough the onboarding steps
    • If prompted for a recipe, select Passwordless
  3. Select the Managed Core option
  4. After your instance is configured, copy the connection URI and API key to your .env file

Start in Dev Mode​

Pfew! That was a lot of setup. Now for the fun part. Run these commands from the root compass directory

  1. Install dependencies

    yarn

  2. Start the backend in dev mode

    yarn dev:backend

  3. Open a separate terminal & start the web app in dev mode

    yarn dev:web

  4. Open the app in your browser: http://localhost:9080

  5. Sign in with one of your authorized test Google accounts

    If all goes well, Compass will:

    • Create a new user in MongoDB
    • Start a user session with Supertokens
    • Add the user's email to Kit (if enabled)
    • Import events from the user's primary Google Calendar into MongoDB
    • Setup a sync channel to receive Google Calendar webhook notifications for the duration specified in the .env (if using HTTPS)

  6. Make a change to the frontend and backend code to confirm each hot reloads

Development Workflow​

Hot Reloading​

Both the frontend and backend support hot reloading during development:

  • Frontend: The React app running on http://localhost:9080 will automatically reload when you make changes to files in packages/web
  • Backend: The Node.js API server running on http://localhost:3000 will automatically restart when you make changes to files in packages/backend

Common Development Tasks​

  • Viewing logs: Check the terminal where you ran yarn dev:backend for API logs and the terminal where you ran yarn dev:web for build logs
  • Testing changes: After making changes, test them in the browser. The app should hot-reload automatically
  • Database inspection: MongoDB collections are created automatically. We recommend using the MongoDB Compass desktop app to visually inspect your database, view collections, documents, and run queries during local development. Connect using the same MongoDB connection string from your .env.local file.
  • Clearing user data: Use yarn cli delete -u <email> to clear a user's data and start fresh (see CLI guide)

Debugging Tips​

  • Use browser DevTools to debug the frontend React app
  • Use Redux DevTools browser extension to inspect Redux state
  • Check backend logs in the terminal for API errors
  • Use MongoDB Compass desktop app to inspect database collections and documents, run queries, and verify data changes in real-time
  • For webhook testing during development, set up Ngrok (see Optional Accounts section)

You already have everything you need, but these tools will make your life easier.

Did we miss something? Please open an issue or PR to help us improve this guide.

Setup Optional Accounts​

Compass will work without these third-parties, but they can be useful for developers and teams who want a batteries-included setup.

Email Marketing: Kit​

Kit is an email marketing service. After a new user signs in, Compass creates a Kit subscriber and adds a tag. You can use this tag to trigger an automation sequence in Kit to send a welcome email to new users.

You can skip this if you don't want to add emails to Kit.

  1. Create a free Kit account
  2. Get your API secret from the Account Settings
  3. Get your Kit tag ID. You can find this in the URL of the tag page
  4. Add the API secret and tag ID to your .env file

Calendar Sync Proxy: Ngrok​

Ngrok exposes local networked services behinds NATs and firewalls to the public internet over a secure tunnel. It allows us to create an agent endpoint that forwards public traffic to localhost Compass API during development so that we can test our webhook endpoints(Gcal etc.) without needing access to a deployed instance..

You can skip this if you're not working on, or going to test the webhook functionalities.

  1. Create a free Ngrok account
  2. Get your Authtoken from the Ngrok Dashboard
  3. Create a Static Domain from the Ngrok Dashboard
  4. Add the Authtoken (NGROK_AUTHTOKEN) and Static Domain (NGROK_DOMAIN) to your .env file

Analytics: PostHog​

PostHog provides analytics and error handling for Compass. This helps track user interactions and monitor application errors to improve the user experience and identify issues.

Like Compass, PostHog is open-source and can be self-hosted. This makes it a good fit for users who are self-hosting Compass for their team and prefer to keep their analytics data in-house.

You can skip this if you don't want to collect analytics or error tracking data.

PostHog Instructions​

  1. Create a free PostHog account
  2. Create a new project in your PostHog dashboard
  3. Get your Project API Key from the Project Settings
  4. Get your PostHog Host URL (usually https://app.posthog.com for PostHog Cloud, or your self-hosted URL)
  5. Add the API Key (POSTHOG_KEY) and Host URL (POSTHOG_HOST) to your .env file

Alternatively, if you prefer to self-host PostHog:

  1. Follow the PostHog self-hosting guide to deploy your own instance
  2. Use your self-hosted PostHog URL as the POSTHOG_HOST value
  3. Get the Project API Key from your self-hosted PostHog dashboard