jsPsych: Enabling an Open-Source Collaborative Ecosystem of Behavioral Experiments

It is common practice to research human behavior using experiments that participants can complete online. Researchers use a variety of methodological approaches to conduct these studies. Some of this research can be done with survey instruments, for which there are many software options. However, much of the research in psychology and human behavior requires tasks that rely on precise measurement of stimulus presentation and response timing, specific kinds of randomization, procedures that adjust based on the responses that are given, and interactive content. jsPsych is a JavaScript library that allows researchers to build the types of experiments that historically could only be run in a lab setting, and run them on any device that has a web browser.


Summary
It is common practice to research human behavior using experiments that participants can complete online. Researchers use a variety of methodological approaches to conduct these studies. Some of this research can be done with survey instruments, for which there are many software options. However, much of the research in psychology and human behavior requires tasks that rely on precise measurement of stimulus presentation and response timing, specific kinds of randomization, procedures that adjust based on the responses that are given, and interactive content. jsPsych is a JavaScript library that allows researchers to build the types of experiments that historically could only be run in a lab setting, and run them on any device that has a web browser.
jsPsych was initially released in 2012 and the early design is described in de Leeuw (2015). This paper is focused on jsPsych version 7, which contains the most substantial set of changes that have been made to the library since its initial release. The software has been widely rewritten with the goals of supporting integration with modern web development tools and improving the developer experience for researchers who want to make contributions to the library. We hope this will make it easier for researchers to collaboratively develop jsPsych and tools that use jsPsych (e.g., Hartshorne et al., 2019;Luchterhandt, 2023;Provenza et al., 2021;Sochat et al., 2016) and encourage researchers with web development experience to contribute to the jsPsych ecosystem.
Highlights of the changes include: 1. JavaScript modules. Refactoring the library to use ES6 modules allows jsPsych developers to take advantage of modern JavaScript development tools like package managers and bundlers. Researchers can now use tools like npm or yarn to integrate jsPsych with their choice of experiment building and hosting environments, and to selectively import jsPsych plugins in their experiment. Researchers can publish their own jsPsych plugins on package repositories and share them with the research community. 2. TypeScript support. We converted the codebase to TypeScript to provide better error checking and better integration with autocomplete and documentation tools that can use type information to assist developers. 3. Simulation mode. Version 7 introduced support for automatically simulating participant behavior, which can be used to robustly test code, experimental design, and analysis pipelines prior to running an experiment. We provide a detailed description of these features and their applications in de Leeuw et al. (2022). 4. Community contributions repository. We created a repository to help community members share their plugins and extensions. We provide templates that are compatible with jsPsych versions 6 and 7 and CI/CD tooling to publish submitted packages to npm.

New plugins and extensions.
We added several new plugins and extensions, including support for recording audio and video responses from participants and mouse tracking.

Statement of need
jsPsych is one of many software options for building online experiments (e.g., Almaatouq et al., 2021;Anwyl-Irvine et al., 2020;Balietti, 2017;Harrison, 2020;Henninger et al., 2021;Mathôt et al., 2012;Peirce et al., 2022;Scott & Schulz, 2017;Stoet, 2017;Zehr & Schwarz, 2018). jsPsych and these other options vary in ways such as available features, closed vs. open source, primary programming language, and syntax/style choices, but the main distinction is the particular way that jsPsych abstracts the design of an experiment. jsPsych experiments are constructed using plugins -self-contained modules that define an event and its parameters. This mode of abstraction allows developers to create both generic plugins that can be used in many different experiments (e.g., show some HTML on the screen and record a keyboard response) and plugins that implement specific experimental paradigms (e.g., display a circular visual search array with a specific number of distractors). Once a plugin is created, it is relatively easy for researchers with no previous web development experience to incorporate the plugin into their own experiments. While some experiment building tools contain abstractions analogous to plugins, it is typically hard for novice web developers to develop and distribute their own plugins.
We have developed a system for jsPsych that makes it easy for researchers to modify existing plugins to suit their needs, create entirely new plugins for their custom tasks, and share these with other psychologists via open-source code (e.g., GitHub) and package (e.g., npm) repositories. This facilitates community-driven, decentralized development. Researchers can develop plugins that abstract an experiment at a level that makes sense for a particular paradigm and then these plugins can be shared with other researchers who want to construct similar experiments. Over the past several years, there have been a handful of researchers who have published articles describing new jsPsych plugins (Donhauser & Klein, 2023;Gibeau, 2021;Kinley, 2022;Kuroki, 2021;Kuroki & Pronk, 2022;Rajananda et al., 2018;Strittmatter et al., 2022). Our community contributions repository, launched in 2021, currently contains 22 plugins and extensions enabling a variety of experiments that would be difficult or impossible to make with the official set of plugins included in the main jsPsych repository. As more users of jsPsych feel comfortable with developing their own plugins and publishing them in easily-accessible repositories, the development work that any individual researcher will need to do to create an experiment will decrease. We hope the changes introduced in version 7 of jsPsych to support this process will enable a robust ecosystem of open-source behavioral experiments.