Jspsych plugin builder

jsPsych Plugin Builder

This skill guides the creation of jsPsych plugins (v8+) following best practices, including when to build new plugins versus using existing ones.

When to Build a New Plugin

Always check existing plugins first before building a new one. Search both:

• https://github.com/jspsych/jspsych (core plugins)
• https://github.com/jspsych/jspsych-contrib (community plugins)

Build a new plugin when:

• No existing plugin provides the needed functionality
• Using an existing plugin would require unintuitive parameterization that doesn't map well to the experimental design
• The parameter usage would be confusing or would force awkward trial structures

Use an existing plugin when:

• It provides the core functionality needed
• Parameters can be configured in an intuitive way that matches the experimental paradigm
• Minor CSS/HTML customization can achieve the desired appearance

When unsure: Show the user a sample trial implementation using an existing plugin. Let them evaluate if the parameterization feels natural for their experiment.

Plugin Development Workflow

1. Determine Distribution Intent

Before initializing, clarify with the user:

• For contribution to jspsych-contrib: Fork and clone jspsych-contrib, then run npx command inside the fork
• For personal use: Run npx command in any directory

This determines the initialization location and subsequent workflow.

2. Initialize Plugin

IMPORTANT: The @jspsych/new-plugin command supports both interactive and non-interactive modes. Always use non-interactive mode when running programmatically (e.g., from Claude Code) to avoid prompt issues:

npx @jspsych/new-plugin --name "plugin-name" --description "Plugin description" --author "Author Name"

Full options:

--name <name>                Name of the plugin package (required)
--description <description>  Brief description of the plugin package (required)
--author <author>            Name of the author (required)
--author-url <url>           Profile URL for the author (optional)
--language <lang>            Language to use: ts or js (default: ts)

For contribution to jspsych-contrib:

# Fork https://github.com/jspsych/jspsych-contrib on GitHub
git clone https://github.com/YOUR-USERNAME/jspsych-contrib.git
cd jspsych-contrib/packages
npx @jspsych/new-plugin --name "my-plugin" --description "My plugin description" --author "Your Name"

For personal use:

npx @jspsych/new-plugin --name "my-plugin" --description "My plugin description" --author "Your Name"

This creates:

• Plugin TypeScript source file
• Jest test file
• Example HTML file
• Documentation template (README.md)
• Package configuration

3. Implement Plugin

Core structure:

• Extend the jsPsych plugin class
• Define plugin info object with name and parameters
• Implement the trial() method
• Handle stimulus display, response collection, and data recording
• Clean up after trial completion

Reference implementations:

• html-keyboard-response: Good model for simple stimulus + response plugins
• html-button-response: Good model for button-based responses

Key principles:

• Use clear, intuitive parameter names that match experimental concepts
• Provide sensible defaults where possible
• Validate parameters and provide helpful error messages
• Record all relevant data (responses, timing, trial parameters)
• Clean up event listeners and timers

4. Write Tests

Create comprehensive Jest tests in the test file:

• Test parameter validation
• Test correct stimulus display
• Test response collection and data recording
• Test timing functionality
• Test cleanup and edge cases

Run tests with npm test

5. Create Examples

Build example HTML files demonstrating:

• Basic usage with typical parameters
• Advanced usage showcasing special features
• Multiple trial variations

Examples help users understand the plugin and serve as integration tests.

6. Write Documentation

Complete the README.md template with:

• Clear description of what the plugin does
• Parameter documentation (name, type, default, description)
• Data generated by the plugin
• Usage examples
• Any special considerations or limitations

Submitting to jspsych-contrib

If the plugin was initialized inside a jspsych-contrib fork:

1. Ensure Completeness

Verify your plugin includes:

• ✓ Source code (TypeScript)
• ✓ Jest tests (passing)
• ✓ Example(s)
• ✓ Complete documentation

2. Create Pull Request

Create a PR from your fork to jspsych-contrib with:

• Clear description of plugin functionality
• Explanation of use cases
• Link to any relevant issues or discussions

Development Tips

Parameter design:

• Use object parameters for complex configurations
• Provide type unions for parameters with limited valid values
• Use callbacks/functions for dynamic behavior

Timing:

• Use jsPsych.pluginAPI.setTimeout() for timing to ensure proper cleanup
• Record timestamps for all important events
• Consider trial_duration and response deadline parameters

DOM manipulation:

• Append elements to display_element provided by jsPsych
• Remove event listeners in the cleanup phase
• Clear timers and intervals

Data:

• Record trial-specific outcomes: responses, response times, accuracy, user interactions
• Do NOT include all trial parameters in the data object (jsPsych has built-in methods for saving parameters separately)
• Focus on what happened during the trial, not what was configured
• Use consistent naming conventions for data fields