Examplary
Start for free
Developer docs

Publishing apps

Apps are published with the Examplary CLI. It builds your app, uploads its files, and publishes the new version, which workspaces then use right away.

Signing in

The CLI publishes as you, so you'll need to be an admin of your workspace. Sign in once in the browser:

npx @examplary/cli login

dev asks you to sign in when you haven't yet, and npx @examplary/cli logout signs you out again. Where there's no browser, like in CI, use an admin's API key from the settings page of your Examplary account instead: pass it with --key, or set the EXAMPLARY_API_KEY environment variable.

Trying out your app

While you work on your app, run this in its folder:

npx @examplary/cli dev

This publishes your own private copy of the app, installs it in your workspace, and opens Examplary in your browser. Whenever you save a file, the copy is updated. While it's installed, it takes the place of the app itself in your workspace, and its hooks get the app's secrets.

The developer toolbar in the browser shows whether it's still connected to dev, with a button to reload once something changed. It has a few panels for your app:

  • Dev app: its capabilities, settings and hooks, and a switch to reload the page by itself whenever something changed.
  • Hook calls: the latest calls of its hooks, with their arguments, result and logs.
  • Cron jobs: its cron jobs, with a button to run one now.
  • App storage: the documents it keeps in storage.

Press Ctrl + C to stop: the copy is then removed from your workspace.

Validating your app

To check your app without publishing it, run this in its folder:

npx @examplary/cli validate

This loads app.ts, checks the app's definition, and bundles its hooks and components to make sure they compile. For question types, it also runs the responseProcessing.testCases you defined, and warns when a component is larger than 100 kB. It's a good check to run on pull requests: inside GitHub Actions, warnings show up as annotations on the files.

To see exactly what would be uploaded, run npx @examplary/cli package. It writes the bundles, the other files, and the app's definition (app.json) to a .bundled folder.

Publishing

npx @examplary/cli publish

Publishing the app again creates a new version, unless nothing changed since the last one. Workspaces that installed it keep their settings and get the new version straight away, or, for a public app, once it's been reviewed. That includes its question types.

To publish an app in a CI environment, make sure the EXAMPLARY_API_KEY environment variable is set with an admin API key, then run npx @examplary/cli publish.

To set a secret, publish the app first, then run:

npx @examplary/cli set-secret ACME_CLIENT_SECRET "..."

Public apps

By default, an app is only available in your own workspace. Set public: true to let every Examplary workspace find and install it:

const app = defineApp({
  id: "acme.gradebook",
  // ...
  public: true,
});

Public apps run code in other workspaces, and their question types show up in the public question type library, so their new versions are reviewed by the Examplary team before they're used, in your own workspace too. You'll get an email when a version enters review, and another once it's approved or rejected. Until then, every workspace keeps using the last approved version. Once an app is public it can't be made private again: publishing a version with public: false is refused. To try out a new version before submitting it, use dev.

Retiring an app

To stop new workspaces from installing your app, publish a new version with deprecated: true. Workspaces that already installed it keep using it.

You can only delete an app (DELETE /apps/{id}) once no workspace has it installed, and never while it's preinstalled; until then the API answers with a 409. Deprecate it instead.

Retiring a question type

To retire one of your app's question types, set deprecated: true on its definition, or leave it out of the app, and publish a new version. Existing questions of that type keep rendering, grading and regenerating everywhere, but no new questions of that type can be created.

Deprecate rather than hide: a public app can't be made private again, because that would stop other workspaces from resolving the definitions of questions they already have, so those questions stop rendering.

Publishing on push to main

You can publish your app from CI, for example with a GitHub Actions workflow:

.github/workflows/publish.yml
name: Publish to Examplary
 
on:
  push:
    branches:
      - main
 
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 24
 
      - run: npm ci
 
      - run: npx @examplary/cli publish
        env:
          EXAMPLARY_API_KEY: ${{ secrets.EXAMPLARY_API_KEY }}