Configuring the jsPsych development environment¶
The jsPsych development setup requires Node.js >= v14 to be installed on your machine.
We recommend that you install version 16 since it includes version 7 of NPM (required for the workspaces feature that the jsPsych repositories use).
If you are bound to Node.js v14, make sure to install NPM v7 manually (via
npm install -g npm@7).
Clone the repository and install the dependencies¶
Clone either the jsPsych repository or the jspsych-contrib repository by running
git clone https://github.com/jspsych/jsPsych.git && cd jsPsych
git clone https://github.com/jspsych/jspsych-contrib.git && cd jspsych-contrib
This will create a
node_modules directory and install all the dependencies into it that are required to build and test jsPsych.
It is important that
npm install is only run in the root directory of the repository (due to the NPM workspaces feature).
If you accidentally ran
npm install anywhere else, remove the
node_modules directory and the
package-lock.json file that were created at that location and run
npm install in the root directory again.
If you are running
npm install in the core jsPsych repository, this will also execute the build chain for all packages in the jsPsych repository.
This step may take a few minutes.
If you would like to use that time efficiently, consider reading the following two sections to know what's happening.
A Node.js package is a directory that contains a
package.json file describing it.
Most importantly, a
package.json file lists other packages that the package depends on.
The jsPsych and jspsych-contrib repositories use NPM workspaces.
That means, running
npm install in the repository root will install the dependencies for all packages in the
The core jsPsych library and every jsPsych plugin or extension is laid out as an individual package.
These packages are published to the NPM registry where they can be downloaded by NPM or any CDN (such as unpkg).
Build chain and build artifacts¶
JsPsych comes with a build chain (specified in the
@jspsych/config package) that can be executed by running
npm run build in a package's directory.
The build chain will read the package (starting at its
src/index.ts file) and create the following build artifacts in the package's
index.jsThis file contains everything from
importing files from the same package). It is used by bundlers like webpack.
index.js, but using the old CommonJS standard to support backwards-compatible tools like the Jest testing framework.
index.browser.jsThis file, like
<script>tag. For plugins or extensions, the default export of a module (i.e. whatever statement comes after
export defaultin the
index.tsfile) is assigned to a global variable. The name of this global variable is specified in the package's
rollup.config.mjsfile, as a parameter to the
makeRollupConfig()function. Hence, for instance, including the
index.browser.jsfile from the
plugin-html-keyboard-responsepackage would assign the
HtmlKeyboardResponsePluginclass to the global
jsPsychHtmlKeyboardResponsevariable. Because the code in
index.browser.jslooks very similar to the
index.tscode but is fully supported by modern web browsers, all examples in the
examplesdirectory reference the
index.browser.jsfiles so users can also modify the source code directly without running the build chain.
index.browser.min.js. It behaves just like
index.browser.min.jsis also processed by Terser to reduce its size and speed up experiment loading times.
*.js.mapWhen debugging code in a browser (especially
index.browser.min.js, which is not easily readable due to Terser and Babel), it is important to be able to read the original source code in the debugger. For every build artifact, there is a
.mapfile which contains a mapping of the generated code to the original source code. Browsers automatically read these
.mapfiles and display the original code in their debuggers instead of the generated one.
Automated code testing for jsPsych is implemented with Jest.
To run the tests, install Node and npm. Run
npm install in the root jsPsych directory. Then run
npm test. You can also run
npm test in the directory of the package that you would like to test. For example, if you are developing tests for the
html-keyboard-response plugin you can run
npm test in
/packages/plugin-html-keyboard-response. If you want to run one file from the root directory, using the aforementioned example, you can run
npm test -- /packages/plugin-html-keyboard-response/src/index.spec.ts.
Tests for the core jsPsych library are located in
Tests for plugins and extensions are located in the
/src folder of the corresponding package. Test files for plugins and extensions are named
There are helper functions for testing in
/packages/jspsych/tests/utils.ts. We recommend looking at other test files to observe conventions for testing.