chandima/h5p-type-scaffold

H5P Content Type Scaffolder

Create a modern H5P content type starting from established boilerplates, with a minimal build pipeline and editor semantics.

How It Works

1. Choose package intent: library-install (default) or content-import (advanced).
2. Collect metadata (title, machine name, version, author, license).
3. Generate a boilerplate (default: SNORDIAN) that aligns with current H5P best practices.
4. Provide starter library.json, semantics.json, and JS/CSS entrypoints.
5. Outline build and packaging steps using h5p-cli.

Concepts

• Content types are runnable libraries under H5P.* (runnable: 1).
• Editor widgets are non-runnable libraries under H5PEditor.* (runnable: 0).
• semantics.json defines the editor form schema and validation rules.
• Non-runnable dependency libraries (often H5P.* or H5PApi.*) are used as shared building blocks.

See references/CONCEPTS.md for details and official links.

Packaging Intent (Required)

• library-install (default): Upload libraries/content types to platform library installers.
• content-import (advanced): Import an authored content instance (h5p.json + content/content.json) into content import flows.
• This skill scaffolds libraries. It does not generate content/content.json.
• Validate unpacked packages before upload:

bash /mnt/skills/user/h5p-type-scaffold/scripts/validate-package.sh --mode library-install --dir /path/to/unpacked
bash /mnt/skills/user/h5p-type-scaffold/scripts/validate-package.sh --mode content-import --dir /path/to/unpacked

Usage

bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Content Type" \
  --machine "H5P.MyContentType" \
  --kind "content" \
  --version "1.0.0" \
  --description "Short description" \
  --author "Your Name" \
  --license "MIT" \
  --template "snordian" \
  --out /path/to/output

Editor widget example:

bash /mnt/skills/user/h5p-type-scaffold/scripts/scaffold.sh \
  --title "My Editor Widget" \
  --machine "H5PEditor.MyWidget" \
  --kind "editor" \
  --out /path/to/output

Output

• library.json and semantics.json
• src/entries, src/scripts, src/styles
• README.md (templates)
• DEV.md (templates, dev harness)
• Build config and lint config (varies by template)
• Templates live under assets/templates/

Build & Package (h5p-cli)

• Install deps: npm install
• Build assets: npm run build
• Set up dev environment: h5p core then h5p setup <library>
• Run local editor/server: h5p server
• Pack library for install: h5p pack <library> [my-library.h5p] (see h5p help pack)
• Install this package in the platform's library/content-type upload flow.
• For library packages, keep library.json at the package root and avoid top-level h5p.json or content/.
• Use h5p.json + content/ only for content-instance export/import flows.
• Run package validation before upload with scripts/validate-package.sh.

Strict-validator packaging (Drupal 11.x H5P 2.0.0+)

Some platforms (notably Drupal 11.x with the H5P 2.0.0 beta module) reject zip directory entries such as dist/ or language/ because they lack an allowed file extension. Use scripts/pack.sh instead of h5p pack to produce a .h5p archive that omits directory entries:

bash /mnt/skills/user/h5p-type-scaffold/scripts/pack.sh \
  --dir /path/to/built-library \
  --out MyLibrary.h5p

Add --strict to abort if any packaged file lacks an allowed extension.

Dev Harness (h5p-cli)

• Manual steps: references/DEV-HARNESS.md
• Helper script: scripts/h5p-dev.sh

xAPI Integration

• Guidance: references/XAPI.md (emit + listen + platform notes)

See references/H5P-CLI.md for a fuller command overview and references/CONTENT-TYPE-AUTHORING.md for authoring essentials.

Guidance (2024/2025 Best Practices)

• Default to the SNORDIAN boilerplate for linting, i18n scaffolding, and CI-ready conventions.
• Use the official h5p/h5p-boilerplate when you want the simplest baseline.
• Prefer vanilla JS for community maintainability.
• Use h5p-cli to pack and manage libraries.
• Validate semantics and editor UX early with a minimal field set.

Related Community Patterns (Incorporated)

• H5P content is often embedded via iframe in LMS or CMS platforms.
• Common education-focused content types include Interactive Video, Course Presentation, Question Sets, Dialog Cards, and Timeline.
• When embedding, wrap iframes in a responsive container and apply safe, minimal styling.

Templates

• snordian (default): Linting + i18n scaffolding + modern webpack config.
• vanilla: Official minimal boilerplate structure.
• editor: H5P editor widget boilerplate (H5PEditor.*).

Additional Upstream Options (Not Bundled)

• h5p/h5p-boilerplate branches like question-type and question-type-vue for specialized starting points.
• otacke/h5p-editor-boilerplate for building custom H5P editor widgets.
• NDLA-H5P/generator-h5p-content-type if you prefer a Yeoman-based generator workflow.
• tarmoj/h5p-react-boilerplate for a React-based starter (note: appears stale).

Troubleshooting

• If machine name is invalid, use H5P.YourContentType.
• For editor widgets, use --kind editor and a H5PEditor.YourWidget machine name.
• If versioning is unclear, start with 1.0.0 and update later.
• If build fails, ensure node and npm are installed and run npm install.
• If import errors mention content/ not allowed, missing preloadDependencies in h5p.json, or invalid license in h5p.json, you are importing a content package into a library upload flow.
• If Drupal 11.x (H5P 2.0.0 beta) rejects the upload with "File 'dist/' not allowed" or "File 'language/' not allowed", the .h5p zip contains directory entries. Repack using scripts/pack.sh --dir <library-dir> which creates a zip without directory entries.