{"id":24288176,"url":"https://github.com/bjoluc/jspsych-builder","last_synced_at":"2025-07-16T12:35:46.351Z","repository":{"id":40297119,"uuid":"257667583","full_name":"bjoluc/jspsych-builder","owner":"bjoluc","description":"A CLI utility to easily develop and package jsPsych experiments","archived":false,"fork":false,"pushed_at":"2024-04-02T11:43:54.000Z","size":5488,"stargazers_count":49,"open_issues_count":7,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-17T10:06:31.734Z","etag":null,"topics":["babel","jatos","jspsych","react","sass","typescript","webpack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bjoluc.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-21T17:34:32.000Z","updated_at":"2025-03-26T18:33:26.000Z","dependencies_parsed_at":"2025-01-16T09:54:02.355Z","dependency_job_id":"081f2bef-e150-42b6-86fa-9c3082064cb9","html_url":"https://github.com/bjoluc/jspsych-builder","commit_stats":{"total_commits":136,"total_committers":6,"mean_commits":"22.666666666666668","dds":"0.27941176470588236","last_synced_commit":"9e33e03bc892c155502f93aa030d30438b8043af"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/bjoluc/jspsych-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoluc%2Fjspsych-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoluc%2Fjspsych-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoluc%2Fjspsych-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoluc%2Fjspsych-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bjoluc","download_url":"https://codeload.github.com/bjoluc/jspsych-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjoluc%2Fjspsych-builder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265509568,"owners_count":23779380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","jatos","jspsych","react","sass","typescript","webpack"],"created_at":"2025-01-16T09:53:44.569Z","updated_at":"2025-07-16T12:35:46.251Z","avatar_url":"https://github.com/bjoluc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jsPsych Builder\n\n[![npm (tag)](https://img.shields.io/npm/v/jspsych-builder/latest)](https://www.npmjs.com/package/jspsych-builder)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/bjoluc/jspsych-builder/build.yml)](https://github.com/bjoluc/jspsych-builder/actions)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\nA CLI utility to easily develop and package [jsPsych](https://www.jspsych.org/) experiments.\n\nFocus on writing your timeline – let jsPsych Builder do the rest.\n\n## Motivation\n\n[jsPsych](https://www.jspsych.org/) can be loaded in three different ways:\nVia a CDN, via standalone scripts, or via NPM (ES6).\nThe latter option, while very convenient, is the hardest to manually set up.\njsPsych Builder solves this by internally configuring common development tools (webpack, Babel, etc.) and exposing them via a simple CLI. Most notably, it:\n\n- sets up the HTML markup\n- provides a development mode with automated browser refreshing (using webpack-dev-server)\n- provides [Sass](https://sass-lang.com/) support\n- helps with media preloading for custom plugins (by compiling lists of file paths to be preloaded)\n- transpiles, bundles, and minifies scripts to guarantee wide browser compatibility and short loading times (using webpack and Babel)\n- provides TypeScript and React support – simply rename your files to `*.ts`, `*.tsx`, or `*.jsx`.\n- supports module-style imports of non-module plugins from `@jspsych-contrib`\n- offers to bundle all the required files for deployment, yielding a zip archive\n- offers to package experiments for [JATOS](https://www.jatos.org/)\n\n## Requirements\n\njsPsych Builder requires [Node.js](https://nodejs.org) \u003e= 14 to be installed on your machine.\n\n## Getting started\n\n\u003e **Attention:** Starting with version 3, jsPsych Builder exclusively supports jsPsych v7. If you need to work with jsPsych v6, consider using jsPsych Builder [v2.1.0](https://github.com/bjoluc/jspsych-builder/tree/v2.1.0) via `npx jspsych-builder@v2 init`.\n\nCreate a new directory, open it in a terminal, and issue\n\n```bash\nnpx jspsych-builder init\n```\n\nThis will ask you a few questions and set up a new jsPsych project for you.\nWithin that project, jsPsych Builder installs itself as a development dependency, so no global package installation is required.\n\nOnce the project has been initialized, you can run `npm start` to start a development server for your experiment.\nYou may then open http://localhost:3000/ to see your experiment in action.\nWhenever you make changes to your source files, the experiment will be updated in the browser as well.\n\nExperiments built with jsPsych Builder adhere to the following directory structure:\n\n```\n├── assets\n├── node_modules\n├── package.json\n├── package-lock.json\n├── src\n│   └── experiment.js\n└── styles\n    └── main.scss\n```\n\n`assets` is the place for your media files, where you are free to add nested directories.\n`package.json` and `package-lock.json` are files created and maintained by npm, a JavaScript package manager.\nYou should leave them in place, as well as `node_modules`, the directory into which npm installs packages.\nThis is also where jsPsych has been saved to.\n\nThe `src` directory is where you write your actual experiments, and `styles` is the place for your custom stylesheets.\nWithin `src`, there can be multiple experiment files, as well as arbitrary directories and JavaScript files that you can `import` in your experiment files.\n`experiment.js` is just the default name for the first experiment file.\nAll jsPsych Builder commands take an `experiment-file` argument to specify which experiment file shall be used.\nBy default, that option is set to `experiment`.\nChanging it to `my-experiment` (for instance via `npm start my-experiment`) would make jsPsych Builder load the `src/my-experiment.js` file instead of `src/experiment.js`.\nThis allows you to have multiple related experiments in one place and share code between them.\n\n## Writing experiments\n\nIf you are new to jsPsych, you might take a look at the jsPsych [demo experiment tutorial](https://www.jspsych.org/latest/tutorials/rt-task/#part-2-display-welcome-message).\nNote that the tutorial [loads jsPsych via a CDN](https://www.jspsych.org/latest/tutorials/hello-world/#option-1-using-cdn-hosted-scripts).\nYou will have to `npm install` and import plugins instead, similar to the [NPM version of the hello-world tutorial](https://www.jspsych.org/latest/tutorials/hello-world/#option-3-using-npm)\n\n### Experiment files\n\nExperiment files need to export an asynchronous `run` function that initializes a JsPsych instance, runs the experiment with it, and optionally returns the JsPsych instance at the end.\nYou can check the [experiment template file](assets/template/src/experiment.tmpl.js) for an example.\nIf the `run` function returns the JsPsych instance, jsPsych Builder will display the results in the browser window at the end (or save them to JATOS when an experiment is served by JATOS).\nRemove the `return` statement from the `run` function if you don't want jsPsych Builder to handle result data.\n\nThe top of the experiment file contains a special section (\"docblock\") with meta information (\"pragmas\").\nThis is where you specify the title, description, and version of your experiment, as well as any asset files and directories.\n\n### Assets\n\nThe `@assets` pragma allows to include arbitrary asset files (like images, videos, etc.) in the build to use them in your experiment.\nThe default value\n\n```\n@assets assets/\n```\n\nincludes all files within the `assets` directory.\nYou can also list individual files and directories, separated by commas.\nFor instance,\n\n```\n@assets assets/my-experiment,assets/fixmark.png,test.html\n```\n\nwould include all files within `assets/my-experiment`, as well as `assets/fixmark.png`, and `test.html`.\n\nThe paths of all matched `asset` files are provided to the `run` function via the `assetPaths` parameter.\nThey are grouped by their media type (`images`, `video`, `audio`, `misc`), so you can preload media files with jsPsych's [preload plugin](https://www.jspsych.org/latest/plugins/preload/) if you need to.\n\n\u003e Migration notice:\n\u003e\n\u003e If you were previously using the `@imagesDir`, `@audioDir`, `@videoDir`, and `@miscDir` pragmas, you can migrate to the `@assets` pragma as shown in the following example:\n\u003e\n\u003e ```diff\n\u003e - @imagesDir images\n\u003e - @audioDir audio/common,audio/my-experiment\n\u003e + @assets media/images,media/audio/common,media/audio/my-experiment\n\u003e ```\n\u003e\n\u003e Note that `@assets` doesn't prefix paths with `media/` like the deprecated `@...Dir` pragmas did.\n\n### Styles\n\nYou can write your style sheets using plain CSS or [Sass](https://sass-lang.com/) (.scss).\nYou may also import style sheets from node packages.\nNote that you have to `import` your styles (or a root style sheet that imports the others) within your experiment file to make the build system include them.\n\n## Packaging experiments\n\nOnce you have finished an experiment, you can run `npm run build`.\nThis will create a zip file containing all the files required to serve the experiment on any machine.\nIf you want to serve your experiment using [JATOS](https://www.jatos.org/), run `npm run jatos` instead to create a JATOS study file (`.jzip`) that can be imported via the JATOS web interface.\n\n## Installing the jsPsych Builder CLI globally\n\nIn case you'd like to have direct access (without `npx` or NPM scripts) to the jsPsych Builder CLI, you can also install jsPsych Builder globally.\nDepending on your system configuration, you may need admin rights to do so:\n\n```bash\nnpm install -g jspsych-builder\n```\n\nIf you are working on Linux or OSX and bash is your shell, you may enable command completion by running\n`jspsych completion \u003e\u003e ~/.bashrc` (Linux) or `jspsych completion \u003e\u003e ~/.bash_profile` (OSX).\n\nA detailed list of sub commands and their respective options can be displayed by running `jspsych` without any options, or `jspsych --help` with the name of a sub command.\n\n## Customizing the webpack configuration\n\n\u003e If you decide to take this path, be aware that even minor and patch releases of jsPsych Builder may break your setup, since the webpack config can be subject to change without notice – you have been warned!\n\nIf you need to, you can customize jsPsych Builder's internal [webpack configuration](https://webpack.js.org/configuration/) to fit your needs:\nIn the root directory of your project (next to your `package.json`), create a `builder.config.mjs` file containing\n\n```js\n/** @param {import(\"webpack\").Configuration} config */\nexport function webpack(config) {\n  return config;\n}\n```\n\nThe function that you export gets the webpack config that jsPsych Builder has assembled internally.\nYou can modify it and return your modified version so jsPsych Builder will use it instead of its own config.\nSimilarly, if you need to alter webpack's [DevServer configuration](https://webpack.js.org/configuration/dev-server/), you can do so via\n\n```js\n/** @param {import(\"webpack-dev-server\").Configuration} devServerConfig */\nexport function webpackDevServer(devServerConfig) {\n  return devServerConfig;\n}\n```\n\nin `builder.config.mjs`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjoluc%2Fjspsych-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjoluc%2Fjspsych-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjoluc%2Fjspsych-builder/lists"}