Mattermost plugins: An overview
Learn about the structure of server and web app Mattermost plugins and how to deploy them
(Originally published at controlaltdieliet.be)
In the first article in this series, you learned how to set up your developer environment, the first step toward creating your very own Mattermost plugins.
Take my word for it: Your first attempts at writing Mattermost plugins can be quite confusing. Where do you start? What do you have to do to get your first plugin up and running?
At the end of this series, you’ll be well on your way to writing your own plugin. But before we get ahead of ourselves, this article provides an overview of the structure of Mattermost plugins.
Plugins let you add more complex features to Mattermost. You can listen to events happening on your Mattermost instance and react to them, you can add extra items to the Main Menu, and you can make interactive dialog boxes for your users, among other things. The possibilities are nearly endless.
Here are some important things you need to know about Mattermost plugins:
- Most plugins have a server part and a web app part.
- The server-side is written in Go. It stores the configuration and interacts with the server or other external hooks.
- In the web app, you can modify the view for the users.
- You can write a plugin that only needs a server part, like the WelcomeBot.
- You can also write a plugin with only a web app part (e.g., if you want to change the font color for certain posts).
- The server-side part needs to be written in Go while the web app part needs to be written in JavaScript.
To get started, you should use the Mattermost Starter Template Plugin since it is minimalistic. While the Mattermost Demo Plugin gives a very nice overview, it can be overwhelming at first (still, it’s a good reference). I also recommend taking a look at the WelcomeBot or the Todo bot as a starting point.
Now that you have a better idea of what Mattermost plugins are like, let’s take a look at some steps you can follow to begin building your own.
Clone the Git repository
First things first: Clone the starter template to your into your development environment.
cd mmplugins
git clone --depth 1 https://github.com/mattermost/mattermost-plugin-starter-template com.example.my-first-plugin
Ignore folders and files
The starter template is already skinned, but there are still folders and files we don’t need. Hooray! 😃
You can safely ignore the .circleci and build folders and the .editorconfig, .gitattributes, .gitignore, .golangci.yml, go.mod, go.sum and Makefile files.
The LICENSE file is important, so read it carefully. Don’t read the README.md; read this article instead!
The most important configuration file: plugin.json
The plugin.json file is the most important configuration file for your plugin. The ID is a unique ID for your plugin. It’s a common practice to use your top-level domain, your domain, your username, and the name of the plugin. To give you a better idea, your ID might be something like:
com.github.controlaltdieliet.my-first-pluginYou will use this ID when installing your plugin.
The next fields are needed, but at this moment they’re less important.
As you begin building your first plugin, you’ll need to enter a name, a description, a version value, and a minimum server value. In the server-side, you find the folder and file name where the executables will be built. In the web app, you’ll find the same for the web app component.
If you are building a server-only app, you simply remove this web app part and the web app folder. If you are building a web app-only plugin, you remove the server part of the configuration and the server folder. You can ignore these settings at this moment.
The next fields are important when you publish your plugin in the Mattermost Marketplace. Other fields to consider include the homepage_url from your site, the support_url where people can file a support ticket, release_notes_url, and icon_path. The settings_schema creates the settings page in the System Console for your plugin. Administrators can set the variables there that your plugin can use.
The assets folder
This is where you can store the binary files that your apps needs — like an icon or a nice pink fluffy unicorn avatar for your newly created bot.
The public folder
This is where you can place the static HTML files that your web app needs. You’re probably safe ignoring this.
The server folder
Coupled with the web app folder, this is the one folder that matters most 😉.
Don’t worry about main.go and manifest.go; configuration.go is where you will define and load all your configuration variables.
The main engine of your server app is plugin.go. It’s the core. In the next article in this series, we’ll explore this file in more depth.
If you want to build a web app plugin only, you need to remove the server folder.
The web app folder
In this folder, you need to know that i18n stands for internationalization, which is used when you’re writing a multilingual plugin. You can ignore all of the other folders and files (except for src, of course).
Here, you will find an index.js or index.tsx that is the hear of your web app plugin. Once again, we will explore these files more in-depth in later articles in this series.
Deploying your plugin
When it comes time to deploy your plugin, go to the mmplugins/mattermost-plugin-starter folder and give this command:
make distAt this point, your plugin will be built, and you’ll receive confirmation.
Now, you have to add your plugin:
../mattermost-server/bin/mmctl plugin add dist/com.mattermost.plugin-starter-template-0.1.0.tar.gz
Finally, you have to enable your plugin:
../mattermost-server/bin/mmctl plugin enable com.mattermost.plugin-starter-template
A handy tip from a pro: Make a script that updates your plugin in one command:
make dist
../mattermost-server/bin/mmctl plugin remove com.mattermost.plugin-starter-template
../mattermost-server/bin/mmctl plugin add dist/com.mattermost.plugin-starter-template-0.1.0.tar.gz
../mattermost-server/bin/mmctl plugin enable com.mattermost.plugin-starter-template Success!
At this point, you’re all set, and you should receive an output that’s similar to this:
Stay tuned for the next installments in this series, which focus on server-side and web app plugins.
Until then, you might be interested in checking out my previous series on Mattermost integrations:
