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

• 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

After you setup your Firebase and Firestore services, add your configurations to

• .firebaserc
• databaseCred-template.ts (which is renamed to databaseCred.ts during install)

You don't need to setup prolific to develop the experiment, but after you've made a prolific project, add the completion code to

• prolificCred-template.ts (which is renamed to prolificCred.ts during install)

Install the dependencies using Yarn (or npm, if you prefer).

###
### From within the cloned repo folder
###

### Install the Firebase dependencies
yarn install ### or: npm install

### Push the Firestore rules (defined in firestore.rules)
yarn deploy-rules ### or: npm run deploy-rules

### Enter the experiment directory
cd "hosting" || exit

### Install the website dependencies
yarn install ### or: npm install

### Start the Vite server
yarn dev ### or: npm run dev

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

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "export ESLINT_USE_FLAT_CONFIG=true && prettier --config prettier.config.mjs --write . && eslint --config eslint.config.mjs --fix . && tsc --project tsconfig.json --noEmit"
  }
}

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

When developing the experiment, you can set const debug = true in globalVariables.ts. This 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

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 (configured in tailwind.config.ts)
• PostCSS (configured in postcss.config.mjs; uses PostCSS Preset Env, which uses Autoprefixer)
• Browserslist (via the browserslist-to-esbuild plugin; configured in hosting/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

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.

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

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

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, 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), activate .vscode via File > Open Folder... in VS Code.

The relevant settings are:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.experimental.useFlatConfig": true,
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "[javascript][javascriptreact][typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json][jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[css][scss][less]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

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 ESLing and Prettier manually:

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

yarn release ### or npm run release

The script will walk you through committing your changes to 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.

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

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.

pip install firebase-admin

Run the script in scripts/retrieve_data.py

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)