Getting started (for developers)

Interested in contributing to Deliberate Lab? Check out easy-to-start open issues

To start running Deliberate Lab locally, clone the PAIR-code/deliberate-lab repository:

# Using HTTPS:
https://github.com/PAIR-code/deliberate-lab.git

# Using SSH key:
[email protected]:PAIR-code/deliberate-lab.git

Repository structure

The Deliberate Lab repository contains the following subdirectories:

• Firebase backend
  • firestore: Firebase security rules for the Firebase backend
  • functions: Cloud functions for the Firebase backend
• Lit/MobX frontend
  • frontend: Frontend web app written in Lit and MobX
• Helpers
  • utils: Package (@deliberation-lab/utils) with types (e.g., Experiment) that are shared across the frontend and backend
  • emulator_test_config: Firebase backend emulators if running the platform locally (without Firebase connection)

Building, running, and developing locally

In order to run the platform locally (using the Firebase emulators instead of a Firebase project for the backend):

1. Build utils (needed for backend and frontend)

cd utils  # If navigating from top level
npm install  # Run this command only once

npm run build:watch  # Build and listen to changes

The shared utilities are built using tsup to produce both esm and cjs (for the cloud functions) code.

Troubleshooting: To manually export the utils package, use npm pack to generate deliberation-lab-utils-1.0.0.tgz. Then, copy this into the directory that requires the utils (e.g., frontend or functions).

2. Build functions (needed for backend)

cd functions  # If navigating from top level
npm install  # Run this command only once

npm run build:watch  # Build and listen to changes

3. Start Firebase emulators (used as backend)

If you haven't already, copy examples to create local configuration files:

# Defines the Firebase project ID
# (can leave example placeholders in while running emulators)
cp .firebaserc.example .firebaserc

# Defines the Firebase project web API key
# (can leave example placeholders in while running emulators)
cp frontend/firebase_config.example.ts frontend/firebase_config.ts

Next, make sure you have Firebase CLI set up:

npm install -g firebase-tools
firebase login

Finally, to run the emulators:

# Start the emulators and load the `emulator_test_config` settings
firebase emulators:start --import ./emulator_test_config

Note: The emulator test config sets up two profiles (experimenter@ and not-experimenter@) for login and adds the experimenter@ profile to the Firestore "allowlist" collection (which enables that profile to create, view, etc. experiments).

Then, access the emulator suite (e.g., auth, Firestore) at http://localhost:4000.

4. Start frontend web app

cd frontend  # If navigating from top level
npm install  # Only run once

# Create an index.html file and (optionally) replace the placeholder
# analytics ID (see TODOs in example file) with your Google Analytics ID
cp index.example.html index.html

# If you didn't already create a firebase_config.ts when setting up
# the emulator, do so now:
#
# cp firebase_config.example.ts firebase_config.ts

npm run start

Then, view the app at http://localhost:4201.

Getting and using your Google Analytics ID

In order for the app to run, you may need to use a Google Analytics ID.

• If you already own one, you can find it by following these instructions.

• If you don't, you need to register one here. Instructions can be found here. At the end of the registration process ("Data Collection"), you will be asked to specify a platform. Select "Web" and (since this is a local project) input localhost.local as the URL.

• After obtaining the Analytics ID (the ID starting with "G-") follow the instructions above. Keep in mind that when including it in JavaScript code, it needs to be a string (e.g. gtag('config', 'G-xxxxx')), while in URLs it must remain without quotes (e.g. gaScript.src=https://www.googletagmanager.com/gtag/js?id=G-xxxxxxxx)

Setting up Firebase configurations

If you encounter an error when signing up as a dummy account, it's likely that you haven't set up your firebase config file. While not necessary for originally getting the app to run, you may need it to get full functionality.

Refer to this manual for creating and using a Firebase API key. Once, the key is created, there should be a generated JSON configuration object in your Firebase project's settings page under the "General" tab. Then copy paste the contents of the JSON object to frontend/firebase_config.ts.

For documentation on navigating the frontend platform as a researcher, see the 🦉 Researchers tutorial in the sidebar.