Plugins

Perseus is extremely versatile, but there are some cases where is needs to be modified a little under the hood to do something very advanced. For example, as you'll learn here, the common need for applying size optimizations requires modifying a file in the .perseus/ directory, which requires ejecting. This is a laborious process, and makes updating difficult, so Perseus support a system of plugins to automatically apply common modifications under the hood!

First, a little bit of background. The .perseus/ directory contains what's called the Perseus engine, which is basically the core of your app. The code you write is actually imported by this and used to invoke various methods from the perseus crate. If you had to build all this yourself, it would take a very long time! Because this directory can be automatically generated though, there's no need to check it into version control (like Git). However, this becomes problematic if you then want to change even a single file inside, because you'll then need to commit the whole directory, which can be unwieldy. More importantly, when updates come along that involve changes to that directory, you'll either have to delete it and re-apply your modifications to the updated directory, or apply the updates manually, either of which is overly tedious for simple cases.

Perseus has plugins to help with this. At various points in the engine, plugins have what are called actions that they can take. Those actions are then executed by the engine at the appropriate time. For example, if a plugin needed to run some code before a Perseus app initialized, it could do that by taking a particular action, and then the engine would execute that action just before the app initialized.

There are two types of actions a plugin can take: functional actions, and control actions. A single functional action can be taken by many plugins, and they (usually) won't interfere with each other. For example, many plugins can add additional static aliases to an app. A single control action can only be taken by one plugin, because otherwise Perseus would have conflicting data. For example, if multiple plugins all set their own custom immutable stores, Perseus wouldn't know which one to use. Both types of actions are explained in detail in the following sections.