@appsemble/sdk

Appsemble SDK

Build your own blocks

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
     * @minLength 10
     * @maxLength 50
     * @pattern ^.+@.*+\..+$
     * @example 'Example string'
     */
    exampleString: string;

    /**
     * This is an number parameter.
     *
     * @type integer
     * @minimum 42
     * @maximum 1337
     * @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;
  }

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

License

LGPL-3.0-only © Appsemble