Developer Docs

Appearance

Extension setup ​

Project setup ​

Template ​

Scaffold a new extension with npm create:

bash
npm create @archilogic/extension-sdk
# or with a project name
npm create @archilogic/extension-sdk my-extension

Two templates are available:

Editor extension (default) — Simple hello world extension with a panel UI:

my-extension/
├── src/
│   ├── index.ts       # mounts the app into the editor panel
├── manifest.json      # host: "editor"
├── package.json
├── tsconfig.json
└── vite.config.ts

Worker extension (--worker) — headless extension with no UI:

bash
npm create @archilogic/extension-sdk my-extension -- --worker
my-extension/
├── src/
│   └── index.ts       # run() function returning data
├── manifest.json      # host: "worker"
├── package.json
├── tsconfig.json
└── vite.config.ts

After scaffolding, install dependencies and build:

bash
cd my-extension
npm install
npm run bundle

npm run bundle compiles the extension and produces a ready-to-upload zip:

my-extension/
└── artifacts/
    └── my-extension-0.1.0.zip   # manifest.json + dist/ bundled together

Basic example ​

For custom setups, add @archilogic/extension-sdk as a dev dependency:

bash
npm install --save-dev @archilogic/extension-sdk

INFO

@archilogic/extension-sdk is a dev dependency only — it is not bundled with your extension. At runtime, the hostApi is injected by the Archilogic host. The package exists solely to provide TypeScript types (e.g. HostApi) for type-checking during development.

ts
import type { HostApi } from '@archilogic/extension-sdk'

export async function run({ hostApi }: { hostApi: HostApi }) {
  const largeMeetingRooms = await hostApi.getSpaces({
    where: { area: { gte: 50 }, category: 'meet' }
  })
  await hostApi.zoomToNode({ nodeId: largeMeetingRooms[0]?.id })
}

Manifest ​

Extensions require a manifest.json to be packaged with the /dist folder

jsonc
{
  "$schema": "https://extensions.archilogic.io/schema/0.6/manifest-schema.json",
  "name": "My extension",
  "description": "This extension is doing custom layout assertions",
  // id of the extension, will be generated after initial deployment
  // required for updates
  "id": null,
  // version of your extension
  // updating an extension requires bumping the version
  "version": "1.5.1",
  // version of the extension-sdk that is used
  "sdkVersion": "0.6.0",
  // relative path to the bundled extension
  "entry": "./dist/index.js",
  // whether the extension runs in 'editor' or headlessly 'worker'
  "host": "editor",
  // whether the extension loads in a side 'panel', a 'popup' or 'none'
  "ui": "panel"
}

Local Development ​

Editor supports loading extensions from localhost.

Make sure Developer Preview features are enabled for your account by the Archilogic Team. With that in place a 'Plugin sandbox' entry appears in the Editor's plugins menu.

You can use vite for previewing and bundling.

bash
npx vite

This will make your extension available at http://localhost:5173/src/index.ts

Copy paste the URL in the 'Load extension' dialog.

Known issues with Vite ​

Dev server CORS blocks the Plugin Sandbox (Vite ≥ 5.4) ​

Vite 5.4 tightened dev-server CORS to prevent DNS-rebinding attacks. As a side-effect, the Archilogic editor (served from app.archilogic.com) can no longer load your extension entry point from localhost. The browser will show a CORS error and the Plugin Sandbox dialog will fail silently.

Fix — add server.cors to your config:

js
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    cors: {
      origin: ['https://app.archilogic.com', 'https://extensions.archilogic.io']
    }
  }
})

process.env.NODE_ENV is undefined in lib mode, crashing Vue inside the iframe ​

Vite's lib build does not replace process.env.NODE_ENV automatically. Vue (and several other frameworks) reference that variable at module evaluation time when deciding whether to enable dev warnings. In a browser iframe that has no process global this throws a ReferenceError immediately on load.

Fix — tell Vite to use the browser build of packages like Vue by setting resolve.conditions:

js
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    conditions: ['browser']
  },
  build: {
    lib: {
      entry: 'src/index.js',
      formats: ['es'],
      fileName: () => 'index.js'
    }
  }
})

Deployment ​

Extensions can be created and updated via the Dashboard UI or via API

Package the extension ​

If you used the npm create template, run:

bash
npm run bundle

This compiles the extension and produces a ready-to-upload zip at artifacts/<name>-<version>.zip.

For a manual setup, configure a Vite lib build pointing to your entry file:

js
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.js',
      formats: ['es'],
      fileName: () => 'index.js'
    }
  }
})
bash
npx vite build

Then create a zip that includes the dist folder and manifest.json.

Make sure the manifest.json

  • correctly references the JS file, e.g. "entry": "./dist/index.js"
  • The id is set properly: "id": null for new extensions or the matching id for updates

Dashboard UI ​

Creation ​

Visit the extensions page in the organization settings

  • Click Add extension
  • Provide a name
  • Upload the zip
  • Click Create

Update ​

  • Click Update Extension in the row's menu
  • Make sure the shown id matches the id in your bundled manifest.json
  • Make sure the version is bumped
  • Upload the zip
  • Click Update

API ​

Check out the API endpoints

Copyright © 2018-present Archilogic