The official source repository for ClassroomIO plugins.
This repository is the canonical source and release pipeline for ClassroomIO's reviewed plugin catalog. Plugin changes enter through GitHub pull requests. Contributors submit source code; ClassroomIO's protected release workflow builds and publishes approved artifacts after merge.
This is not the ClassroomIO application backend or Plugin SDK repository. Those live in
classroomio/classroomio. Plugins in this repository
are frontend packages or declarative contributions. They do not run their own ClassroomIO backend
and do not receive ClassroomIO credentials. Sandboxed plugin interfaces use the public Plugin SDK
to request permission-checked host capabilities, including installation-scoped plugin storage.
| Plugin | What it contributes | Data access |
|---|---|---|
| Announcement Banner | An academy banner and organization settings page | Organization and user-scoped plugin storage |
| Certificate Studio | A certificate template picker and organization design page | Certificate template write access and organization-scoped plugin storage |
| Course & Live Calendar | An organization page and course sidebar schedule | Course, lesson, and exercise metadata |
| Creative Landing Templates | A landing-page template picker and public renderer | No ClassroomIO data permission |
| Lesson Policy Acknowledgment | A learner acknowledgment widget after lesson content | User-scoped plugin storage |
| LinkedIn Certificate Sharing | A host-rendered certificate action that opens LinkedIn | No ClassroomIO data permission or stored customer data |
| Reading Time Estimator | A reading-time widget after lesson content | Computed lesson metadata |
All seven plugins are currently release-enabled in registry/plugins.json.
plugin-conformance is a non-releasable fixture used to test the hosted plugin
contract.
Each plugin owns its source, manifest, dependencies, tests, and build configuration inside one
top-level directory. Its plugin.json declares what ClassroomIO may load or render:
- identity, version, compatibility, and packaged assets;
- custom UI entrypoints or host-rendered contributions;
- supported slots, pages, navigation items, templates, or actions;
- required permissions and external network origins;
- whether it stores customer data and how long retained data may remain after uninstall;
- host-managed storage documents and their schemas, when storage is needed.
The registry is the release allowlist. A directory is not publishable merely because it exists in
the repository. Its registry ID must match its manifest ID, release must be enabled, and the
repository verification rules must pass.
plugins/
├── .github/workflows/ # Pull-request validation and protected releases
├── registry/plugins.json # Reviewed plugin and release allowlist
├── scripts/ # Release verification, upload, and registration
├── announcement-banner/ # One self-contained plugin
├── certificate-studio/
├── course-calendar/
├── landing-templates/
├── lesson-acknowledgment/
├── linkedin-sharing/
├── reading-time/
└── plugin-conformance/ # Test fixture; never released
Fork classroomio/plugins, then clone your fork and add
the upstream repository:
git clone git@github.com:<your-github-username>/plugins.git
cd plugins
git remote add upstream git@github.com:classroomio/plugins.git
git switch -c feat/<plugin-or-change>The Plugin SDK boundary packages are linked from the ClassroomIO repository until those packages
are published independently. For local builds, clone classroomio/classroomio beside this
repository. The following layout matches the GitHub repository names; the sibling ClassroomIO
checkout must be named classroomio so the current link: dependencies resolve:
workspace/
├── classroomio/
└── plugins/
The GitHub workflows pin a specific ClassroomIO commit. For the closest match to CI, use the
ref configured for the classroomio/classroomio checkout in
the pull-request workflow. See
.github/PRODUCTION_DEPLOYMENT.md
for why the SDK is pinned and the migration path to an independent npm package.
Use the versions declared by .nvmrc and packageManager in
package.json. Build the linked SDK once, then install this workspace:
cd ../classroomio
pnpm install --frozen-lockfile
pnpm --filter @classroomio/plugin-sdk build
cd ../plugins
pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm run pack
pnpm release:verifyUse pnpm run pack, not bare pnpm pack. The repository command builds every release-enabled
registry entry and writes deterministic archives plus release-index.json under the ignored
.plugin-artifacts/ directory. Bare pnpm pack creates an npm package tarball instead.
For an existing plugin:
- keep changes inside that plugin's directory unless a repository-level contract must change;
- increment
plugin.json.versionwhenever released plugin code, assets, or behavior changes; - request only the permissions, storage, and network origins the plugin actually uses;
- add or update tests for behavior changes;
- do not import private ClassroomIO modules such as
@cio/*,$lib/*, or$app/*; - do not import source from another plugin directory.
For a new community plugin:
- use a reverse-domain plugin ID controlled by you, such as
com.example.reading-timer; - add one self-contained top-level plugin directory;
- add its ID, path, kind, and reviewed release state to
registry/plugins.json; - include
build,check, andtestscripts before requesting release; - document permissions, allowed network origins, stored customer data, and retention behavior.
The com.classroomio.* namespace is reserved for first-party plugins. Registry inclusion and
catalog release remain subject to maintainer review.
Push your branch and open a pull request against classroomio/plugins:main. Complete the pull
request template, include manual test steps, and sign the ClassroomIO Contributor License Agreement
when requested.
Pull-request CI runs without production release credentials. It:
- checks out the plugin source and the pinned ClassroomIO SDK boundary;
- installs locked dependencies;
- runs repository checks and tests;
- builds and verifies all release-enabled plugin archives;
- rebuilds the archives and compares their digests to prove deterministic output;
- uploads the review artifacts to GitHub Actions with seven-day retention.
Maintainers review the source, manifest capabilities, data policy, dependency boundary, tests, and generated artifact report before merge.
Most UI plugins expose standard Vite commands. For example:
pnpm --dir announcement-banner run dev
pnpm --dir announcement-banner run build
pnpm --dir announcement-banner run testdev serves the plugin interface directly for frontend work. It does not install the plugin into
ClassroomIO.
For integrated testing, use the repository packager and the ClassroomIO database seeder. The
packager removes old build output, rebuilds every release-enabled plugin, and writes canonical
artifacts to .plugin-artifacts/:
# In plugins
pnpm run pack
# In classroomio (auto-discovers ../plugins when cloned side-by-side)
pnpm --filter @cio/db db:seed:pluginsConfigure PLUGIN_ARTIFACTS_PATH in apps/api/.env (in classroomio) to point to the artifacts output:
PLUGIN_ARTIFACTS_PATH="/absolute/path/to/plugins/.plugin-artifacts"The database command registers every packaged official plugin and version, installs or updates them
for all organizations currently in the local database, and grants each manifest's required
permissions. If your plugins checkout is in a non-standard location, provide PLUGINS_DEV_PATH=/path/to/plugins
when running db:seed:plugins. Re-run both commands whenever plugin source, assets, permissions, or
manifest data changes so the database digest and served artifacts stay synchronized.
- In
plugins: No.envfile is required for the canonicalpnpm run packworkflow. - In
classroomio: SetPLUGIN_ARTIFACTS_PATHinapps/api/.envso the local ClassroomIO API serves iframe assets directly from.plugin-artifacts/:PLUGIN_ARTIFACTS_PATH="/absolute/path/to/plugins/.plugin-artifacts" - Optional SDK CLI (
cio-plugin dev/cio-plugin seed): Only needed when testing a single plugin development server without building the full catalog. SetCLASSROOMIO_API_URL,CLASSROOMIO_DEV_TOKEN, andCLASSROOMIO_ORG_IDas shown in.env.example.
cio-plugin dev remains available in the SDK for targeted development-release API testing, but it
is not the canonical workflow for maintaining this official repository. Do not run the root
workspace as a single plugin; it has no root plugin.json.
Contributors do not upload production artifacts and do not call the production registration API.
The release workflow runs from protected main through the
plugin-production GitHub Environment.
For an approved release, the workflow:
- repeats the locked install, checks, tests, packaging, verification, and deterministic rebuild;
- selects eligible release entries affected by the merge and rejects a changed plugin whose manifest version was not incremented;
- uploads assets and archives to immutable, digest-qualified object-storage paths;
- creates a GitHub build-provenance attestation for the release archives;
- asks the ClassroomIO internal release API to verify and register the approved versions.
Existing objects are never silently overwritten. A retry is accepted only when the existing bytes match the locally verified artifact.
Maintainer-only repository protections and production release infrastructure are documented in
.github/BRANCH_PROTECTION.md, .github/PRODUCTION_DEPLOYMENT.md, and .env.example.
Release verification rejects, among other invalid states:
- duplicate registry IDs or paths and manifest/registry ID mismatches;
- first-party namespace misuse or a releasable fixture;
- missing build, check, or test scripts for release-enabled plugins;
- unapproved local dependencies, unpinned external dependencies, and private host imports;
- imports that escape a plugin directory;
- oversized archives, unexpected inventory, links, source maps, environment files, and key files;
- release artifacts whose version, manifest, digest, paths, or extracted bytes do not match the canonical release index.
Do not commit dist/, .plugin-artifacts/, npm tarballs, credentials, local environment files,
private keys, or source maps.