5 Minute Quick Start

Hello World Plugin

Let's create a simple "Hello World" plugin that responds with a JavaScript alert "Hello, Developer!" when a user says hello world on a tab with a *.lipsurf.com domain.

  1. Clone the community plugins repository and change into the directory.
git clone https://github.com/LipSurf/plugins.git lipsurf-plugins
cd lipsurf-plugins
  1. Install the dependencies.
yarn install
  1. Create a folder named HelloWorld with a HelloWorld.ts file in it with the following contents:


It's important to keep the capitalization consistent. The case-sensitive namespace must always end in Plugin (eg. HelloWorldPlugin) and the folder and file name should have the same name and capitalization (without the Plugin suffix).


Rather than copy-pasting, it's better to type out the code to force yourself to grasp it's intuitive structure and contents better.

// lipsurf-plugins/src/HelloWorld/HelloWorld.ts
/// <reference types="lipsurf-plugin-types"/>
import { PluginBase } from '../PluginBase';

export module HelloWorldPlugin {
    export let Plugin: IPlugin & IPluginBase = Object.assign<{}, IPluginBase, IPlugin>({}, PluginBase, {
        niceName: 'Hello World',
        description: 'A hello world plugin that works on the lipsurf.com domain.',
        // a RegEx that must match against the current tab's url for the plugin to be active (all of it's commands minus global commands)
        match: /.*\.lipsurf.com/,
        version: '1.0.0',

        commands: [{
            name: 'Respond',
            description: 'Respond with something very insightful to the user',
            // what the user actually has to say to run this command
            match: 'hello world',
            // the js that's run on the page
            pageFn: function() {
                alert('Hello, Developer!');

The meat of the plugin lives in the array of commands. Each Command object has a match property for what the user needs to say to run it, a pageFn property for the code that's actually run and a bunch of meta properties like name, description etc.

  1. Since we're doing the example in TypeScript, we need to compile down to JavaScript.
yarn watch


This will watch our *.ts files for changes and compile them to JavaScript whenever a change is detected 😃

  1. Time to load 'er up. Open up Google Chrome and right click the LipSurf icon then "Options".

  2. Turn on "Developer mode" by checking its box.

Screenshot of developer mode setting

  1. Click "Add a Local Plugin" under "Plugins" and navigate to the compiled .mjs file (eg. plugins/dist/HelloWorld.mjs).


The mjs extension is special for ECMAScript modules (ESM). They are basically JavaScript.

Screenshot of the

🏁    That's it!    🏁


After a few seconds your plugin should appear in the plugins list if there were no installation problems.


Check the developer console (<F12>) for hints if there are installation issues.

Screenshot of the HelloWorld plugin in the list of plugins

Now try saying hello world on this tab (since this tab has a lipsurf.com domain it will match our url pattern).

If everything went smoothly, you should see a JavaScript alert like this one:

Screenshot of

You can also say help to see your new command listed in the auto-generated help overlay.

Screenshot of help cheat-sheet that now includes new

What's Next

If you think that's nifty, we've just scratched the surface! LipSurf can handle homophones, dynamic match commands, multiple languages and more!

Check out the "Advanced" topics after you've regained composure from all the excitement this is generating!

Last updated: 1/11/2019, 3:28:20 PM