Examplary
Start for free
Developer docs

Building apps

Apps allow developers to extend Examplary with new features and integrations.

They connect Examplary to other platforms and extend it with new question types. Workspace owners and admins can install apps from the Apps & Integrations section in their workspace settings.

Our own integrations, like Google Classroom, Woots, Schoolyear and Safe Exam Browser, are built as apps, using the same tools described here.

The anatomy of an app

An app is a package that defines a set of Capabilities. These capabilities determine what the app can do within Examplary, such as adding new question types, integrating with external services, or providing custom dashboard pages.

An app is a folder with an app.ts file that describes it, and other files that contain the actual logic and UI components of the app.

Getting started

Create a new app with the Examplary CLI:

npx @examplary/cli init acme-gradebook --id acme.gradebook --name "Acme Gradebook"

This creates a folder with an app.ts, and a package.json with the Examplary packages and scripts to run and publish the app.

Make sure that your app.ts has a defineApp call that defines your app and exports it as the default export.

app.ts
import { defineApp } from "@examplary/apps";
 
import exportOption from "./capabilities/export";
 
const app = defineApp({
  id: "acme.gradebook",
  name: { en: "Acme Gradebook" },
  description: { en: "Send tests to your Acme classes" },
  icon: "./icon.svg",
});
 
app.addSetting({
  key: "apiToken",
  label: { en: "Acme API token" },
  help: { en: "You'll find it in your Acme account settings." },
  type: "password",
  secret: true,
});
 
app.addCapability(exportOption);
 
export default app;

The id identifies your app on the platform and can't be changed later. Use a reverse domain-like name, in lowercase: <your-org>.<app-name>.

To try it out in your workspace while you build it, run this:

npm run dev

To publish it to your organization, or submit it for public use, follow the steps in the publishing guide.

App properties

The defineApp function is used to define your app and its properties:

PropertyDescription
idUnique ID, like acme.gradebook. Required.
nameDisplay name. Required.
descriptionOne-line description, shown on the app's card. Required.
iconPath to a square icon (SVG or PNG).
readmePath to a Markdown file with a longer description.
previewImagePath to a preview image.
websiteWhere to read more about the app.
versionYour own version number, like 1.2.0.
scopeWho fills in the settings by default: the workspace (org) or each teacher (user). See settings.
apiScopesThe Examplary API scopes your hooks can use, like ["audit-logs:read"]. See hooks.
publicWhether every Examplary workspace can find and install the app. See publishing.
deprecatedExisting installations keep working, but the app can no longer be installed.
requiredPlansThe plans a workspace needs to install the app or change its settings: any of free, pro or enterprise. All plans when left out.

Texts like name and description are translatable: give an object with a value per language ({ en: "…", nl: "…" }). Paths are relative to the app's root folder; the CLI uploads the files they point at.

Directory structure

Apart from app.ts, you're free to organize your app however you like.

A typical app might look like this:

acme-gradebook/
├── app.ts
├── package.json
├── icon.svg
├── README.md
├── capabilities/
│   └── export.ts
├── components/
│   └── connect-button.tsx
└── lib/
    └── acme-api.ts

app.ts can import from other files and npm packages, as long as they don't rely on Node.js APIs. See hooks for what's available.