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.

Acquire an API key

You'll need the API key of an admin of your workspace. You'll find it on the settings page of your Examplary account. You can also provide it through the EXAMPLARY_API_KEY environment variable, instead of passing --key every time.

Validating your app

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

npx @examplary/cli app validate

This loads app.ts, checks the app's definition, and bundles its hooks and components to make sure they compile. It's a good check to run on pull requests.

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

Publishing

npx @examplary/cli app upload --key YOUR_API_KEY

Uploading the same app again publishes a new version. Workspaces that installed it keep their settings and get the new version straight away, or, for a public app, once it's been reviewed.

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

npx @examplary/cli app set-secret ACME_CLIENT_SECRET "..." --key YOUR_API_KEY

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, so their new versions are reviewed by the Examplary team before other workspaces get them. A new version is usable in your own workspace right away. You'll get an email when it enters review, and another once it's approved or rejected. Until then, other workspaces keep using the last approved version.

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.

Publishing on push to main

Just like question types, you can publish your app from CI, for example with a GitHub Actions workflow:

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: 22
 
      - run: npm ci
 
      - run: npx @examplary/cli app upload
        env:
          EXAMPLARY_API_KEY: ${{ secrets.EXAMPLARY_API_KEY }}