In this post we’re going to take a deep dive into Firefish Plugins. By the end, you’ll be able to make informed decisions about the safety of a plugin and know how to install them.

What is Firefish?

Firefish is an ActivityPub based social media platform with a growing community and a focus on 👯‍♂️ fun and 🎨 creativity. It’s a fork of another platform called Misskey, which is highly popular in Japan.

In addition to the standard fediverse features you’ve come to know and love in our social media platforms (posting, liking, hashtags, boosts, etc.) Calckey adds quite a few unique features that make it worth checking out. Channels, Groups, Pages, Antennas, Widgets and Plugins to name just a few!

Today we’re talking about Plugins, what they are, how they work, and how to install them.

Plugins Overview

One of the many unique features Firefish provides is the ability to apply plugins to the instance’s website.

At it’s core, a plugin is a script that can be copied into a textbox in your account settings. A few ways plugins can be used to affect your Firefish experience:

• Alter notes displayed in your feed
• Add a new feature to the post submission dialog
• Add a new feature to the notes action items
• Add a new feature to the profile action items

Plugins are created by the community base and installed by each end user as desired. There is not currently a central repository for plugins, so you’ll need to find them on your own.

Plugins are available on the official Firefish instance’s website and the installed progressive web app based on the same site.

Plugins are saved to your browser’s local storage, and removed when you clear your cache, but are still available if you log out and back in. They don’t automatically follow you to logins on a different browser, private mode or a different device.

You CAN save your scripts to a local file and/or to your Firefish instance by backing up your Firefish Preferences, found in Settings > Preferences backups. This preference backup can then be restored or loaded on other devices! This a great way to backup and load your plugins when you want to use them on multiple devices.

The preferences backup includes more than just your plugins, consisting of your custom css, themes and other preferences you’ve configured.

Misskey Plugins

MissKey plugins are mostly authored in Japanese, so it can difficult to understand what they do, even using a translation service. In addition, not all MissKey plugins will work on Firefish as of this writing. Finally, there is no single repository for plugins for either platform, so finding vetted, safe plugins can be a challenge.

I want to thank all of the MissKey plugin authors for their hard work and creativity. Without their contributions, I absolutely wouldn’t have been able to understand Plugins and AiScript at all! 🙏

The Difference Between Plugins and Widgets

Widgets offer a deeper integration with Firefish than Plugins. They can alter the layout of the site itself and are written in plain html and javascript (Vue.js to be exact). Because of this, they require review, approval and installation by the instance’s admins. Firefish offers a default set, but instances can install their own or remove the defaults from their sets if they so desire.

Widgets are often more fully featured than a specific Plugin. Plugins, however, add a level of customization freedom for the individual user that wouldn’t be available through Widgets.

Firefish Plugin Fundamentals

Even if you don’t plan on creating your own plugins, understanding the basics of how they work will help you make informed decisions about the plugins you want to install.

AiScript - Javascript with Guardrails

Plugins are written in a language called AiScript. The language provides access to a small sub-set of javascript features like variables, constants, strings, arrays, etc. AiScript is configured to only allow changes to the objects that are passed into the handlers, such as note, post or profiles objects.

Currently there are two major versions of AiScript. Ones that were built with AiScript version 0.12 or lower and those built with higher versions. Breaking changes occurred at that point. Firefish is currently running version 0.11.1 and scripts built with newer versions will not work out of the box.

Breaking it down

A plugin consists of three main areas: Configuration, Functions, and Handlers. If you’re only interested in installing plugins, you should at least understand the Configuration metadata.

Configuration Metadata

The configuration metadata section must contain a name, version and author of the plugin. This is actually all you need to install a plugin, and is a good place to start.

With just this, a plugin won’t do anything, but you can see it in the Plugins section.

1
2
3
4
5
6
7
8
9

/// @ 0.11.1
### {
  name: "Box464's Cool Plugin"
  version: "0.11.1.0.001"
  author: "@box464@calckey.social"
  description: "Your cool plugin description"
  permissions: []
  config: {}
}

The first line of code denotes the specific version of AiScript that is required to run the Plugin. While not required, this is highly recommended.

1

/// @ 0.11.1

For Calckey, the version should be 0.11.1, but it may soon be transitioning to 0.13.3.

Firefish is currently undergoing major changes, including possible updates to AiScript, the underlying programming language used to create plugins. These would be breaking changes, and would require all plugins to be updated to work with the new version.

The two versions are not compatible, so it’s important to know which version the Plugin is using. Note that many of the Misskey Plugins you’ll find have already moved to 0.12.x and higher, and those will not work for Firefish instances right now.

If the plugin you want to install doesn’t list the version at the top of the code, an easy way to identify the version is to look for variable declarations in the code itself, since 0.11.1 and 0.13.3 use completely different syntax.

Version 0.11.1 looks like this:

1
2
3

$myVariable <- yes
#myConstant = "Hello World"

Version 0.13.3 looks this this:

1
2

var myVariable = true
let myConstant = "Hello World"

Permissions

Permissions allow the plugin to make calls to the Firefish API.

Permissions can be as simple as reading your own timeline, or as complex as writing and SENDING posts for you, or as destructive as deleting content or updating your profile information.

If you see permissions listed in a plugin, be even MORE certain you trust the author. You will see a “permissions” prompt when installing the plugin, and you’ll need to accept those permissions before the plugin will be enabled.

A sample configuration showing the permissions required to read your pages collection:

1
2
3
4
5
6
7
8
9
10

/// @ 0.11.1

### {
  name: "Connect to the API"
  version: "0.11.1.0.001"
  author: "@box464@calckey.social"
  description: "Connecting to the API demonstration"
  permissions: ["read:pages"] // This plugin requires the ability to read your pages collection
  config: {}
}

Installing a Plugin

NOTE: 🙏🏽 🚨 ONLY INSTALL PLUGINS FROM A TRUSTED SOURCE! 🚨 🙏🏽

Got it? Good. I personally vetted (and wrote) the plugin sample provided in this article. All of the scripts I write or vet have no malicious intent, but I can’t guarantee that will always be the case for other plugins you find on the internet.

Here’s a sample plugin that you can install to test out the process. It’s a simple plugin that will add an action item to each note in your timeline and display a dialog with a custom message of your choosing, along with displaying the User Name of the current note’s author.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

/// @ 0.11.1
### {
  name: "Display an Alert"
  version: "0.11.1.0.001"
  author: "@box464@calckey.social"
  description: "Display an alert dialog box with your own custom message from the note action menu."
  permissions: []
  config: {
    message: {
      type: "string"
      label: "Display Message"
      description: "The message to show on the alert dialog."
      default: "You did it!"
    }
    enabled: {
      type: "boolean"
      label: "Enabled"
      description: "If enabled, the display message will appear in a modal window on new plugin install or update of settings."
      default: yes
    }
     debug: {
      type: "boolean"
      label: "Enable Debugging"
      description: "Write debugging information to the console."
      default: no
    }
  }
}

@debug(comment) {
  ? (Plugin:config.debug = yes) {
    print("Plugin: Display a Modal")
    print(comment)
  }
}

// Create an object to hold the configuration variables
#c = {}
c.message <- Plugin:config.message
c.enabled <- Plugin:config.enabled

// Break your code into a handler function and an effect function for clarity

@handler(note_) {
  debug("Begin Handler")

  ? (c.enabled = yes) {
    debug("Dialog display is enabled")

    $note <- effect(note_)
  }

  debug("End Handler")

}

@effect(note) {
  debug("Begin Effect")
  debug(note)

  Mk:dialog(c.message Arr:join(["Author of Note: " note.user.username]))

  debug("End Effect")
}

Plugin:register_note_action("Display an Alert" handler)

You can find plugins in the Settings > Plugins section of your Firefish site. Click “Install Plugin” and paste the plugin code into the text area.

After you install a plugin, you have to click the Plugin menu item again to view the installed plugin. If your plugin has a syntax error of some type, you will immediately get feedback and won’t be allowed to save the plugin.

A few things may happen next.

• On success, it will show a check mark, the reload the page (it will be empty)
• If the plugin requires access to the Firefish Api, you’ll be prompted to accept those permissions before the plugin will be enabled.
• On a failure to save, it will most likely show a syntax error dialog without much else to help out.

If you aren’t following my guidance and just downloading random plugins that aren’t curated by a trusted source, note that many of these plugins won’t work on Firefish. They may have been created for MissKey, which has upgraded their AiScript version, making them incompatible with Firefish’s version.

Using a Plugin

You might need to configure some settings on the plugin before you can use it. These will be available in the plugin’s settings dialog. Not every plugin will have a settings dialog.

Plugins will be active by default, but be sure to check the “Activate” toggle in the plugin’s settings dialog to make sure it’s enabled as well.

Depending on the plugin you’ve installed, it will appear in one of the following places:

• As a new action item in the note’s action menu
• As a new action item in the profile’s action menu
• As a new action item in the post submission dialog
• As changes to the notes in your timeline

For our example, head back to any of your timelines, and check the hamburger menu attached to a note. You’ll see your new action item.

Click it, and see your modal in action. It should show your custom message, along with the Note Id.

Congratulations, you just installed your first Firefish plugin!

Time to tinker. Change the settings of your plugin and see what happens.

• Change the custom message
• Flip the enabled flag - now the modal shouldn’t pop up when the menu item is selected.
• Bonus Points: Try returning a value from the note object other than note.user.username

Want to see it in action? Here you go:

Conclusions

Plugins are underrated and under-utilized in the Firefish community. There are good reasons for this - lack of documentation not the least among them. MissKey enthusiasts have built a small library of plugins, but most are listed and described in Japanese. Finding ones that you can trust is difficult. And finding ones that work on Firefish is even more scarce, akin to a scavenger hunt.

Firefish needs more documentation, which will hopefully lead to more plugins. There also needs to be a trusted source for them, so that we can be confident that the plugins we install are safe and secure. Something akin to a Plugin Store.

Next up…

Now that you know the fundamentals of installing plugins, I’ll introduce a few new ones to try out! Finally I’ll cover how to create your own custom plugins, diving even deeper into the specifics of AiScript and plugin development. Stay tuned.