create-jspsych-plugin

Scaffold jsPsych plugin packages with multi-plugin support, docs-driven development, and a maximally capable build config.

Setup

cd create-plugin
npm install
npm run build
npm link

After npm link, the create-jspsych-plugin command is available globally.

Usage

Create a new project

Interactive:

create-jspsych-plugin

Non-interactive:

create-jspsych-plugin --name sokoban --plugins "solve,edit,rate" --react --author "Your Name"

Add plugins to an existing project

cd jspsych-sokoban
create-jspsych-plugin add compare select

This creates plugin files, docs, dev pages, and examples, then patches src/index.ts, rollup.config.mjs, package.json, and dev/index.html.

CLI Reference

create (default command)

| Flag | Description | |------|-------------| | --name <name> | Project name (e.g. "sokoban") | | --description <desc> | Project description | | --author <name> | Author name | | --plugins <list> | Comma-separated plugin names (e.g. "solve,edit,rate") | | --react / --no-react | Include React (default: false in non-interactive) |

If --name and --plugins are omitted, runs in interactive mode.

add <names...>

Adds one or more plugins to an existing project. Must be run from the project root (where package.json lives). Detects React mode automatically from dependencies.

What Gets Generated

A project like jspsych-sokoban with plugins solve, edit, rate:

jspsych-sokoban/
├── package.json          # Per-plugin exports, build scripts
├── rollup.config.mjs     # TSX, CSS injection, asset inlining, scheduler shim
├── tsconfig.json         # JSX always enabled, strict mode
├── jest.config.cjs       # jsdom, CSS mocking, ready when needed
├── vite.config.ts        # React plugin conditional
├── CLAUDE.md             # Architecture guide for Claude Code
├── docs/
│   ├── architecture-paradigms.md
│   ├── sokoban-solve.md  # Plugin spec (parameters, data, behavior)
│   ├── sokoban-edit.md
│   └── sokoban-rate.md
├── scripts/
│   └── check-docs.ts     # Validates docs match plugin info objects
├── examples/             # Standalone HTML examples per plugin
├── src/
│   ├── index.ts          # Barrel re-export of all plugins
│   ├── shared/           # types/, core/, rendering/, utils/, assets/
│   └── plugins/
│       ├── sokoban-solve/
│       ├── sokoban-edit/
│       └── sokoban-rate/
└── dev/                  # Dev menu + per-plugin test pages

Design Principles

• Claude Code first — Non-interactive flags are the primary interface. Generated CLAUDE.md describes the architecture.
• Docs-driven development — Each plugin has a spec in docs/. The info object derives from it. npm run check-docs keeps them in sync.
• Always multi-plugin — Even a single plugin uses src/plugins/ + src/shared/. Adding more is just add <name>.
• Maximally capable build — Rollup handles TSX, CSS injection, asset inlining, and the scheduler shim by default. No config changes needed when adding React, Konva, Zustand, etc.
• Minimal opinions on rendering — Only "Include React?" changes generated code. Everything else is "add the dep and use it."

Tool Structure

create-plugin/
├── src/
│   ├── cli.ts            # Commander with "create" and "add" subcommands
│   ├── prompts.ts        # Interactive prompts
│   ├── naming.ts         # toHyphenated, toPascalCase, derivePluginNames, etc.
│   ├── context.ts        # Builds TemplateContext from options
│   ├── generator.ts      # Renders EJS templates to output directory
│   └── add-plugin.ts     # Reads existing project, patches files
├── templates/
│   ├── _partials/        # Reusable rollup config partials
│   ├── project/          # Project-level templates (rendered once)
│   ├── plugin-common/    # Per-plugin files (always generated)
│   ├── plugin-dom/       # Plain DOM plugin template
│   └── plugin-react/     # React plugin + Trial component templates
└── docs/
    └── common-plugin-types.md  # Internal reference for plugin patterns