Introduction

• Windy Plugins are small web applications, that are running inside Windy.com environment.
• They are written in Typescript and Svelte
• Windy.com uses Leaflet map library (slightly patched version 1.4.X) with easy to use API
• Svelte and Typescript are optional, and you can write your plugins in vanilla JavaScript

Creating your first plugin

Start by cloning our Windy Plugin Template from GitHub.

git clone https://github.com/windycom/windy-plugin-template.git
cd windy-plugin-template
npm install
npm start

Your first plugin should be built and served at https://localhost:9999/plugin.js

Your plugin directory is pretty straightforward.

├── dist
│   └── built code...
├── examples
│   ├── 01-hello-world
│   ├── 02-using-vanilla-js
│   ├── 03-boat-tracker
│   ├── 04-aircraft-range
│   └── 05-airspace-map
├── src
│   ├── plugin.svelte
│   ├── pluginConfig.ts
│   └── screenshot.jpg
├── package.json
└── tsconfig.json

What is plugin.svelte

The plugin.svelte file is the main file of your plugin. It is a Svelte component, but as we have said before you do not need to use Svelte to make your plugin. If you wish you can use it just as a template for your HTML, CSS and Typescript (or JavaScript code).

<section class="plugin__content">
    <small>This is my first plugin</small>
</section>
<script lang="ts">
    import { onDestroy, onMount } from 'svelte';

    onMount(() => {
        // Your plugin was mounted
    });

    onDestroy(() => {
        // Your plugin was destroyed
    });
</script>
<style>
    small {
        color: yellow;
    }
</style>

What is pluginConfig.ts

The pluginConfig.ts file is a simple Typescript file, that exports a configuration object (see Plugin Configuration).

import type { ExternalPluginConfig } from '@windy/interfaces';

const config: ExternalPluginConfig = {
    name: 'windy-plugin-my-plugin',
    version: '0.1.0',
    icon: '🔌',
    title: 'This is my first plugin',
    description: 'This is my first plugin.',
    author: 'John Doe (optional company name)',
    desktopUI: 'rhpane',
    mobileUI: 'fullscreen',
};

We could not make it more simple.

Lifecycle of the Plugin

As a developer, you have just minimal work.

Windy.com will take care of:

• Installation of your plugin, upon user's request
• Updates of your plugin, when you release a new version
• Changing of browser's URL to https://www.windy.com/plugin/your-router-path so your plugin can be opened from URL (if perviously installed)
• Changing browser's title to your plugin's title

Whenever is your plugin opened, your HTML and CSS code is attached to page and the Svelte's method onMount is called.

After that exported onopen method is called, if it is defined.

When your plugin is closed, the Svelte's method onDestroy is called.

Remember that all the methods above are optional, so if you do not want to handle any of this events, you do not need to define them.

Just remember, that while methods onMount and onDestroy are called only once during lifecycle of the plugin, the onopen method can be called multiple times, so do not put any listeners here.

export const onopen = (params: unknown) => {
    // Your plugin was opened with parameters parsed from URL
    // or with LatLon object if opened from contextmenu
};

onMount(() => {
    // Your plugin was mounted
});

onDestroy(() => {
    // Your plugin was destroyed
});

Opening plugin with parameters

onopen method is called with parameters parsed from URL or with LatLon object if opened from contextmenu.

For example, if you define routerPath in your pluginConfig.ts as /hello-world/:lat?/:lon?, then your plugin will be opened with parameters { lat: string; lon: string } parsed from URL.

Importing other libraries

Beside your own code, you can import any code installed as npm package in node_modules.

Windy.com modules are imported with @windy/ prefix.

Importing types MUST use import type statement, otherwise Svelte compiler will throw an error.

// Importing Windy.com API module
import { store } from '@windy/store';

// Importing code installed in node_modules
import { onMount } from 'svelte';

// Importing your local code
import { myMethod } from './myPluginLibrary';

// Importing types
import type { LatLon, ExternalPluginConfig } from '@windy/interfaces';

WARNING

Since Leaflet library is already up and running in Windy.com, we have problems with importing Leaflet plugins, that are using L object, as npm packages.

If it happen to you, copy/paste desired code to your plugin directory and import it as local code.