Write, test, share

How to start coding

1. Create a JS/TS file

my-plugin.ts

function init() {
    // This function is called when the plugin is loaded
    // There is no guarantee as to when exactly the plugin will be loaded at startup
}

2. Create a manifest file

The ID should be unique, in case of a conflict with another extension, your plugin might not be loaded

Here we're going with Typescript.

We're setting isDevelopmentto true in order to be able to quickly reload it when we make changes. payloadURI in this case is the path to the plugin code, it must be an absolute path.

Obviously, before sharing the extension we'll change the payloadURI to the URL of the file containing the code and remove isDevelopment.

my-plugin.json

{
    "id": "my-plugin",
    "name": "My Plugin",
    "version": "1.0.0",
    "manifestURI": "",
    "language": "typescript",
    "type": "plugin",
    "description": "An example plugin",
    "author": "Seanime",
    "icon": "",
    "website": "",
    "lang": "multi",
    "payloadURI": "C:\path\to\my-plugin.ts",
    "plugin": {
        "version": "1",
        "permissions": []
    },
    "isDevelopment": true
}

3. Quick overview

a. Permissions

Most APIs aside from basic ones require specific permissions in order to function.

The user of your plugin will need to acknowledge them before the installation.

b. Hooks

You can register hook handlers to listen to various types of events happening on the server and modify them.

For example:

function init() {
   // This hook is triggered before Seanime formats the library data of an anime
   // The event contains the variables that Seanime will use, and you can modify them
   $app.onAnimeEntryLibraryDataRequested((e) => {
      // Setting this to an empty array will cause Seanime to think that the anime
      // has not been downloaded.
      $replace(e.entryLocalFiles, [])
      
      e.next() // Calling this so other hooks listening
   })
}

Each hook handler must call e.next() in order for the hook chain listening to that event to proceed. Not calling it will impact other plugins listening to that event.

c. UI

Hooks are great for customizing server-side behavior but you might want to provide some visual feedback to the user like showing alerts or even displaying custom content.

function init() {
   
   // This function registers the UI context for your plugin, allowing it to
   // have access to UI APIs
   $ui.register((ctx) => {
   
      ctx.screen.onNavigate(() => {
         // Displays an annoying alert each time the user navigates.
         ctx.toast.info("Hello!")
      })
      
   })
}

d. Javascript restrictions

Due to the way plugins are run under the hood, some behaviors will not work.

let globalVar = 42;

function init() {
    let value = 42;
    
    // When init is run, the hook registers the callback (e) => {}
    // Under the hood, this callback will be run by different "virtual machines" or runtimes, whenever the hook is triggered.
    $app.onGetAnime((e) => {
        // Hence, variables declared outside this scope will always be undefined. 
        console.log(globalVar) // ⛔️ undefined
        console.log(value) // ⛔️ undefined
    })
    
    $ui.register((ctx) => {
        console.log(globalVar) // ⛔️ undefined
        console.log(value) // ⛔️ undefined
    })
}

However, you can still share variables between hooks and the UI context using $store.

e. Types

Add the type definition files located here.

https://raw.githubusercontent.com/5rahim/seanime/refs/heads/main/internal/extension_repo/goja_plugin_types/app.d.ts

app.d.ts

https://raw.githubusercontent.com/5rahim/seanime/refs/heads/main/internal/extension_repo/goja_plugin_types/plugin.d.ts

plugin.d.ts

https://raw.githubusercontent.com/5rahim/seanime/refs/heads/main/internal/extension_repo/goja_plugin_types/system.d.ts

system.d.ts

my-plugin.ts

/// <reference path="./plugin.d.ts" />
/// <reference path="./system.d.ts" />
/// <reference path="./app.d.ts" />

function init() {
    // Everything is magically typed!
}

4. Write and test

You're good to go!

Code the extension

APIs

UI

Hooks

Test it live

In order to test your plugin, add the manifest file inside the extensions directory which is inside your data directory.

Because you've set isDevelopement to true in your manifest file, you will be able to manually reload the extension without having to restart the app. It's recommended to test your plugin with the web-app version of Seanime for convenience.

5. Share

If you want to share your plugin with others, you can host both the code and manifest file on GitHub and share the link to the file.

Make sure to replace payloadURI with the URL of the hosted file containing the code.

Also, remove isDevelopment .