@appsemble/sdk

Appsemble SDK

Build your own blocks

Table of Contents

• Installation
• Usage
  • bootstrap
  • TypeScript interfaces
    • Parameters
    • Actions
    • Events
    • Messages
• License

Installation

npm install @appsemble/sdk

Usage

bootstrap

The bootstrap function registers a function which gets called every time a new instance of the block is created. If the block returns a DOM Node, it’s attached to the block’s shadow root.

The function may be asynchronous, but should not wait for actions to have finished, as actions are delayed until all blocks on a page are ready.

import { bootstrap } from '@appsemble/sdk';

bootstrap(({ utils }) => {
  const root = document.createElement('span');
  root.textContent = utils.formatMessage('hello');
  return root;
});

TypeScript interfaces

Various block settings can be defined by augmenting interfaces in @appsemble/sdk. This allows you as a block developer to work in a type safe manner, while providing validation and documentation for users implementing your block in their app.

Parameters

Block parameters can be defined by augmenting the @appsemble/sdk#Parameters interface. The Appsemble CLI will automatically create a JSON schema from these type definitions. This includes the TSDoc comments. It’s highly recommended to properly document this interface, as generated documentation is user-facing. JSON schema properties can be written as TSDoc tags. Markdown is supported in descriptions.

declare module '@appsemble/sdk' {
  interface Parameters {
    /**
     * This is an example string parameter.
     *
     * @format email
     * @maxLength 50
     * @minLength 10
     * @pattern ^.+@.*+\..+$
     * @example 'Example string'
     */
    exampleString: string;

    /**
     * This is an number parameter.
     *
     * @type integer
     * @maximum 1337
     * @minimum 42
     * @multipleOf 3
     * @example 123
     */
    exampleNumber: number;
  }
}

Actions

Block actions can be defined by augmenting the @appsemble/sdk#Action interface. Only the action keys and TSDoc descriptions are used. Markdown is supported in descriptions.

declare module '@appsemble/sdk' {
  interface Action {
    /**
     * This is an example action.
     */
    onClick: never;
  }
}

Events

Block event emitters can be defined by augmenting the @appsemble/sdk#EventEmitters interface. Block event listeners can be defined by augmenting the @appsemble/sdk#EventListeners interface. For both emitters and listeners, only the keys and TSDoc descriptions are used. Markdown is supported in descriptions.

declare module '@appsemble/sdk' {
  interface EventEmitters {
    /**
     * This is an example event emitter.
     */
    data: never;
  }

  interface EventListeners {
    /**
     * This is an example event listener.
     */
    refresh: never;
  }
}

Messages

Block messages can be defined by augmenting the @appsemble/sdk#Messages interface. The values of these properties are used for type safety when calling utils.formatMessage(). Markdown is supported in descriptions.

declare module '@appsemble/sdk' {
  interface Messages {
    /**
     * This message doesn’t support variables
     */
    bye: never;

    /**
     * This message accepts a variable named `name`.
     */
    hello: {
      name: string;
    };
  }
}

License

LGPL-3.0-only © Appsemble

Changelog

[0.27.12] - 2024-04-10

Added

• App: Add support for app variables.
• Cli: Add support for app variables and secrets from the app directory.
• Server: Add AppVariable table to store app variables.
• Studio: Add an app Variables page to the studio.
• Utils: Add app variable endpoints.
• Utils: Add the variable remapper.