CKEditor-Components (@accredify/custom_ckeditor)

A custom CKEditor 5 build used by Accredify-Dashboard. The editor source lives here; webpack bundles it into a single self-contained dist/bundle.js, which is what gets published to npm and loaded by the Dashboard.

What this package provides

dist/bundle.js auto-initialises CKEditor on elements it finds in the page:

| Selector | Features | |----------|----------| | #emailTemplate, #edit_emailTemplate | Bold, Italic, Underline, Link, WordCount, and 8 template-variable dropdowns | | .ck-editor | Heading, Bold, Italic, Underline, Link, bulleted/numbered List, WordCount | | .ck-editor-markdown | Everything in .ck-editor plus Markdown + Source Editing toggle |

The 8 variable dropdowns (certificate, badge, recipient, course, institution, issuer, wallet pass, issuance date) insert template tokens such as {{certificateName}} or {{issuanceDate_ddmmyyyy}} at the cursor. Their items come from per-editor config in app.js (e.g. certificateVariables, issuanceDateVariables).

Tech stack

• CKEditor 5 v48 — the single consolidated ckeditor5 package, used under the open-source GPL licence (licenseKey: 'GPL'). See Licensing.
• webpack 5 — bundles everything (incl. CKEditor CSS) into dist/bundle.js.
• pnpm (pinned via the packageManager field) on Node 22.
• Node's built-in test runner + Puppeteer for end-to-end tests.

The published package has no runtime dependencies — consumers receive the prebuilt bundle, not the source or the build toolchain.

Prerequisites

• Node 22+
• pnpm — easiest via Corepack (ships with Node):

  corepack enable

  Corepack reads the packageManager field and uses the pinned pnpm version automatically. (Or install pnpm yourself: npm i -g pnpm.)

Develop

pnpm install            # install dependencies
pnpm dev                # build dist/bundle.js (development mode)
pnpm prod               # build dist/bundle.js (production, minified)

The tests run in a headless Chromium that Puppeteer manages. pnpm install fetches it automatically; if it is ever missing, install it explicitly:

pnpm exec puppeteer browsers install chrome

dist/ is git-ignored and built on demand — it is not committed. CI rebuilds it before every publish, so the published bundle always matches source.

Testing & verification

The test suite loads the real built dist/bundle.js in headless Chrome (Puppeteer) and exercises every editor — this is the source of truth for "does it work?", because the package's behaviour only exists in a browser.

For AI agents / automated checks

Run a single command from the repo root:

pnpm test

This builds the bundle first (pretest) and then runs the suite. Success looks like this (and the process exits 0):

# tests 30
# pass 30
# fail 0

A non-zero exit or any # fail > 0 means something regressed — read the TAP output for the failing assertion. The single most important guard is the initializes all four editor instances without console/page errors test: it turns red on CKEditor licence errors (e.g. the v47 LTS/GPL wall) and on broken/renamed imports, which are the classic upgrade failures.

What the 30 tests cover:

• Initialization — all four editor types create successfully, zero console/page errors, each editor's word-count widget is wired into its wrapper, and the bundled CKEditor CSS is injected and applied (style-loader + css-loader).
• Toolbar — all 8 variable dropdowns register on #emailTemplate (12 toolbar items).
• Variable insertion — for both #emailTemplate and #edit_emailTemplate, every configured value of all 8 dropdowns inserts the correct {{token}} text, and labels match.
• Plain HTML editor (.ck-editor) — expected commands present; headings and lists round-trip as HTML.
• Markdown editor (.ck-editor-markdown) — getData() returns markdown, not HTML; bold, links, headings and lists round-trip; the source-editing toggle is present.

For humans (visual check)

pnpm prod                                   # build the bundle
open test/fixture.html                      # macOS (or open the file in any browser)

The fixture loads ../dist/bundle.js. In the page you should see four working editors. Verify by hand:

1. Each editor renders a styled toolbar (CKEditor CSS is applied).
2. On the email-template editor, open any "Add … variables" dropdown and click an item — the {{token}} text is inserted at the cursor.
3. In the markdown editor, type/toggle the source editing (</>) button and confirm content is markdown.

Note: test/fixture.html and the suite are dev-only — they are not part of the published package.

Continuous integration

.github/workflows/test.yml runs pnpm test on every pull request and push to master, so regressions are caught before release.

Publishing

Publishing is automated via GitHub Releases — you no longer run npm publish locally. The CI workflow builds, runs the full test suite, and only then publishes, so a broken build can never reach npm.

Authentication uses npm Trusted Publishing (OIDC) — there is no token or secret to manage. GitHub Actions proves its identity to npm directly, which is more secure than a long-lived publish token (and is what npm recommends over automation tokens).

One-time setup on npmjs.com (an account with publish rights to @accredify): open the package page → Settings → Trusted Publisher → GitHub Actions, and enter:

| Field | Value | |-------|-------| | Organization or user | Accredifysg | | Repository | CKEditor-Components | | Workflow filename | publish.yml | | Environment | (leave blank) |

(Trusted publishing requires the package to already exist on npm — it does.)

To release a new version:

1. Bump version in package.json (and description) in a PR, and merge it to master.
2. Create a GitHub Release with a tag that matches that version, prefixed with v — e.g. package.json "version": "1.7.0" → tag v1.7.0. Write release notes.
3. Publishing the release triggers .github/workflows/publish.yml, which builds, tests, verifies the tag matches package.json (it fails the release if they differ), and publishes to npm via OIDC.

The git tag and package.json version are kept in lockstep — the version field is the single source of truth, and CI enforces it.

Provenance attestations are generated automatically only for public repositories. This repo is private, so provenance is skipped; trusted-publishing authentication still works regardless of visibility.

What gets published (the npm tarball)

npm publish packs the files listed in the files field into a gzipped tarball — that tarball is the package: it is uploaded to the npm registry and unpacked into a consumer's node_modules on install. For this package the tarball contains only:

dist/bundle.js
dist/bundle.js.LICENSE.txt
dist/bundle.js.map
package.json
README.md

(No source files or build config — consumers only need the bundle.) Preview it any time without publishing: pnpm pack --dry-run.

Using the updated version in Dashboard

Bump the dependency to the new version:

"@accredify/custom_ckeditor": "^1.7.0"

Dashboard loads the bundle directly (dist/bundle.js).

Licensing

This build uses CKEditor 5 under the GPL terms (licenseKey: 'GPL' in every ClassicEditor.create() call — mandatory since CKEditor v44).

It is pinned to the v48 line, not v47: the v47.x line entered LTS maintenance in April 2026, and post-maintenance 47.x releases are commercial-only and reject the GPL key (license-key-lts-not-allowed). v48 is the current regular line usable under GPL. If Accredify obtains a commercial CKEditor licence, replace 'GPL' with the licence key in app.js.