Getting started with the Plugins SDK

Requirements

  • NodeJS (any recent version >=12 will do)
  • npm
  • yarn (this is optional but below commands use it)

Create your Livestorm plugin

First off, install the Livestorm plugin CLI :

yarn global add @livestorm/cli

Then run :

livestorm create

This will guide through a few steps required to configure your plugin.

API Token

The creation process will prompt you for an API token. This token is the link between your plugin and your Livestorm account.

Any plugin published with this API token will be available within the organization associated with the token.

📘

To obtain a Livestorm API token, follow these steps : Authorization

Dependencies

Once created, you'll notice that the created folder is nothing more than a preconfigured Javascript library.

You can of course add and manage dependencies with yarn. Do not hesitate to take a look at the package.json file to have an idea of what the project is shipped with.

In general, since this is a regular npm package you have access to pretty standard npm commands that allow you to manage your dependencies and run your test suite.

yarn
yarn test

Go to an event room

Livestorm plugins are activated within event rooms (where events take place).

That means that to test your plugin, you will need to jump into an event of your organization (new or existing) on which your plugin will be activated.

If you need to create an event, you can follow this guide.

📘

Please note that plugins are only compatible with regular events. Instant meetings are not supported.

Start building

Once you have completed the above steps, you should be ready to start coding.
Open your project folder and open the src/app.ts file.

This is the entry point of your Livestorm plugin. This code is executed in a sandboxed Javascript environment which communicates directly to Livestorm via a standard iframe <> DOM communication.

import Livestorm from '@livestorm/plugin'
/*
*
* The `Livestorm` object contains all of the exposed APIs that allow 
* you to act and build on top of the Livestorm room
*
* Do not hesitate to console.log(Livestorm) or use the autocompletion of your editor 
* to understand what is inside and what are the exposed APIs
*
*/


/*
*
* A simple Hello world example consists in publishing an event that everyone
* in the room is going to subscribe to
*
*/
Livestorm.PubSub.subscribe('say-hello', (payload) => {
  console.log('Someone said :', payload.message) 
})

/*
*
* Then, once you have subscribed to the said event
* You will be able to publish it to all of the subscribers
* ie: everyone who is in the room will receive the message
*
*/
Livestorm.PubSub.publish('say-hello', { message: 'Hello world' })


Setup your development env

Setting up your local environment properly will allow you to benefit from the JSDoc documentation.

It allows you to write code much more rapidly and without having to do regular back and forth between your code and the online documentation.

This is the kind of feedback you should expect from your editor when writing a plugin :

The easiest way to benefit from typescript linting and JSDoc is to use Visual Studio Code editor.
With another editor, install a JSDoc and Typescript extension.

Publishing

Whenever you want to try your plugin or publish it for good, simply run :

livestorm publish

This will publish your plugin based on the API token and version number you set in the package.json

In the development phase it is advised that you use the watch command that allows iterate much faster.

livestorm watch

it will automatically run the publish command whenever you make a change in your code.

To see the result in the room simply refresh the page.

📘

Learn more about the Publish process

To learn more about the publish process, it is advised that you read the Environments page.

Going further

In this video you are going to dive into the APIs of the SDK to build an actual plugin.

Follow our entire video course on Wistia.

Need a hand?

We are here to help, feel free to drop an issue at our Github repo or to contact us directly at plug[email protected].