serverless jsPsych Template (jsPsych-Firebase-Firestore-Prolific-Vite)

This repository is an example of how to setup a development environment for building online psych experiments. Key aspects are:

• TypeScript centric
• Future-looking linting and formatting configuration using ESLint and Prettier
• Vite bundler for robust cross-platform support
• jsPsych for UX flow
• serverless data handling with Firestore
• Firebase hosting
• Prolific integration

Installation

• Fork this repo: Use this template > Create a new repository
• Git clone the forked repo (replace with your repo info): e.g. git clone --branch main https://github.com/daeh/jspsych-template.git jspsych-template
• Enter the repo folder (replace with your repo info): e.g. cd jspsych-template

Install Node Dependencies

Install the dependencies using Yarn

```shell

From within the cloned repo folder

Install the Firebase dependencies

yarn install

Start the Vite server

yarn dev ```

Usage

You can format, lint and build the project from the command line by calling the commands in package.json:

To develop the website, run yarn dev, which will open a localhost Vite server that will update as you make modifications.

Sandbox

You don't need to set up Firebase, Firestore or Prolific to develop the experiment. This app comes built to start development immediately. There are primarily two toggles to help with sandboxed development, which are found in appConfig.ts.

• Setting const debuggingMode = true will increase the verbosity of the console output.

  • Alternatively, you can force debugging mode by including debug as a URL Parameter, e.g. https://mysite.web.app/?debug=true

• Setting const simulateMockDatabase = true will make the app use a serverless emulator so that you don't have to set up Firestore before beginning development.

  • Similarly, you can modulate the backend with a URL Parameter, e.g. https://mysite.web.app/?debug=false&mock=true

Configuration

Components

For developing the website, this project uses

• ESLint (configured in eslint.config.mjs)
• TypeScript (configured in tsconfig.*.json)
• Prettier (configured in prettier.config.mjs)

The ESLint config integrates these configurations.

For bundling the website, this project uses

• Vite (configured in vite.config.mts)
• Tailwind CSS
• PostCSS (configured in vite.config.mts; uses Autoprefixer)
• Browserslist (via the browserslist-to-esbuild plugin; configured in package.json)
• jsPsych - UX (experiment flow, data capture)

For serving the website, this project uses

• Firebase - hosting (configured by files in the project root)
• Firestore - serverless data storage/access (configured by files in the project root)
• Prolific - recruitment

ESLint

This project uses a future-looking configuration that implements the major developments from ESLint. The main config file in this repo is the flat ESLint config, eslint.config.mjs.

Flat Config System

Beginning in ESLint v9.0.0, the default will be the new flat config system. This will deprecate the Common.js Module config system (which uses .eslintrc.js), replacing it with the ES Module config system (which uses eslint.config.js).

Stylistic Plugin

ESLint is deprecating formatting rules, passing over maintenance and development to the community-run plugin ESLint Stylistic.

IDE

VS Code Settings

For VS Code to respect the configuration, you need to specify the formatter for the relevant files. This is done for you in VSCodeProject.code-workspace and in .vscode/settings.json (these are redundant, you only need one). This configures the ESLint extension to use the flat config system, makes VS Code use the Prettier - Code Formatter extensions for formatting filetypes not covered by ESLint, and enables Tailwind CSS IntelliSense. This obviously requires that you have these extensions enabled for the workspace. Activate the VSCodeProject.code-workspace via File > Open Workspace from File... (or by double-clicking it), or activate .vscode via File > Open Folder... in VS Code.

The relevant settings are:

IntelliJ IDEA Settings

For IntelliJ IDEA / WebStorm to respect the configuration, you need to enable ESLint and Prettier for the relevant filetypes. There is an example config in .idea. To enable ESLint and Prettier manually:

Integrations

Hosting and Database

Firebase and Firestore Configuration

Data Collection

Prolific Configuration

Deploying an experiment

The script scripts/releaseScript.mjs automates deployment of the experiments. You can run it from the root directory with:

shell yarn release

The script will walk you through committing your changes to the git repo that you forked.

A key idea here is that there should never be ambiguity about what code was served to a participant.

The releaseScript.mjs prompts you to increment the version number, generates a new git commit, injects the version number and the git commit's SHA hash variables into the static website, and then deploys the website to Firebase. The version and hash variables are stored alongside a user's responses.

Retrieving Data

Retrieve the data from Firestore using the Firebase Admin SDK, which you must authorize with credentials from your Firebase project.

Generate credentials to access the firestore database

1. Go to the Firebase Console.
2. Select your project.
3. Navigate to "Project settings" > "Service accounts".
4. Click "Generate new private key" and save the JSON file.

Save credential in an encrypted disk image (NOT IN YOUR GIT REPO)

Install Firebase Admin SDK

shell pip install firebase-admin

Download the data

Run the script in scripts/retrieve_data.py

shell python retrieve_data.py \ --cred "~/Desktop/myproject-firebase-adminsdk.json" \ --out "~/Desktop/dataout" \ --collection 'exptData' 'sharedData'

• --cred the path to the private key you downloaded from Firebase.
• --out the path to a directory where the files will be saved (the directory will be created; the path cannot exist yet)
• --collection the collections to download (during development, these are exptData-dbug and sharedData-dbug)

Author