Project Organization

This project directory is organized to be very modular and composable. In general, files and functions should be relatively small and self-contained, global scope should not be used and only the pieces of code needed for any given file should be imported. This keeps the code maintainable with clear lineage and purpose for each piece of code.

Almost all of the changes needed for custom JsPsych tasks will be done in the src/ folder.

assets/

This folder contains any static files that are used by the app. Honeycomb starts with a few images used as icons for the installed applications.

build/

The build scripts automatically create a build folder at the root of the repository and update it on subsequent builds. build/ should be left alone!

caution

The build folder is in Honeycomb's .gitignore and as such should never be added to git

emulator_data/

This folder contains starter data for the Firebase Emulators to use while developing locally. See the Firebase Scripts to use the data - emulator_data/ should be left alone!

env/

This folder contains different .env files used to pass environment variables (secrets and/or settings) into Honeycomb. Honeycomb starts with presets for common use cases and is explained in greater detail in the Environment Variables section.

node_modules/

danger

node_modules/ is written to when running npm install and should never be manually edited.

psiturkit/

The file psiturk-it inside psiturkit/ is a bash script used to instal PsiTurk locally - see Deploy Online for more information. psiturkit/ should be left alone!

public/

The public directory contains files that are used as assets in the built app.

• favicon.ico is the small icon you can see in the browser tab.
• index.html is the entry point of the website
  • Changing <title>Honeycomb</title> will update the name you can see in the browser tab.
• electron.js contains all of the code related to the electron app.

lib/

The lib/ directory contains the files PsiTurk needs to run. Note that index.html references these files inside the <script> tags

config/

The config directory contains the config files needed for the electron app. This includes the event-marker details and event codes. version.json keeps track of the current git commit, which Honeycomb uses to keep track of the version of your task used for a given experiment.

src/

This folder contains the source code for the Honeycomb application.

__tests__/

Automated test cases should be created in this folder.

assets/

Any assets used by your task should be stored here, such as images and videos.

note

These assets are not statically generated like the root assets/ folder. Only assets needed by your task should go here.

components/

The React components that make up Honeycomb are located here.

• App.jsx initializes and maintains the state of the application. It is also where communication is set up between the electron and psiturk processes.
• Error.jsx displays a small error message. It is rendered when the App.jsx detects an issue in state.
• JsPsychExperiment.jsx initializes the JsPsych experiment
• Login.jsx handles user authentication based on the environment variables passed to Honeycomb

config/

Each file in the config directory contains settings for a different part of the task.

• main.js contains the global settings (e.g. whether Honeycomb is running online or in the clinic) passed from env variables and logic for loading the appropriate language file.
• trigger.js for equipment-related settings (e.g. event markers). It uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.

Other config files can be used to add settings for specific blocks or sub-sections of the experiment.

language/

Any language that is displayed in the experiment should be stored in this folder. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) and mturk-specific language. Common phrases can be written once in a language file and re-used throughout the task.

lib/

The utility functions and markup used in the tasks are located here. This allows for functions and html to be re-used wherever needed.

markup files contain HTML templates used throughout the task. Typically this will be a function that takes in some parameters and then returns a string with html.

tip

Be sure to look through utils.js for functions you might be able to use in your task

timelines/

A timeline is a collection of trials that JsPsych displays in the given order. Timelines can contain timelines themselves; you may want to break this nesting into multiple files in this folder.

main.js contains the root timeline which App.jsx loads into the <JsPsychExperiment> component.

trials/

A trial is the base unit of a JsPsych experiment. Each trial should be its own file within this folder - the files in src/timelines/ will combine these trials into the full experiment.

firebase.js

firebase.js contains all of the logic for creating, reading, and updating data in Firebase. You should not have to update this file.

index.css

index.css contains all of the styling in the application. Classes can be defined here and referenced in your markup.

index.js

index.js is the entry point for React in our application. Note that the id 'root' corresponds with a tag in public/index.html:

<div id="root"></div>

Other Files

• .github/workflows/ contains .yaml files used to build Honeycomb on a pull request (build.yaml) and create task executables either in a single instance (package.yaml) or for a full release (release.yaml)

• package.json contains metadata about your project, a list of the dependencies needed for the project, and scripts to run tasks related to your task. The Quick Start lists which metadata should be changed.

• download-response-data.js is the script used to download data stored in Firestore to your local machine.

• version.js is the script used to keep track of which version of the task a given experiment is using

danger

package-lock.json is written to when running npm install and should never be manually edited.

Git Files

• .gitignore lists the folders and files that should be excluded from Git. Make sure all of your secrets and tokens are listed here!

Eslint Files

• .eslintrc.js contains the Eslint settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.
• .eslintignore lists the folders and files that eslint shouldn't touch, similar to .gitignore.

Prettier Files

.prettierrc.js contains the Prettier settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.

Firebase Files

• .firebaserc contains the name of the project Firebase should connect to. Be sure to update the default project to the one you created!
• firebase.json contains the Firebase settings for Honeycomb. It should be left alone!
• firestore.indexes.json contains the Firestore index settings for Honeycomb. It should be left alone!
• firestore.rules contains the Firestore rules for creating/editing data. It should be left alone!