Decky Plugin Template

If your plugin includes a backend, you must follow a specific directory structure to ensure the decky-plugin-database CI can correctly package your binaries.

Directory Requirements

• Source Code: All backend source code must be located in backend/src relative to the root of your git repository.
• Output Binaries: During the build process, all finished binaries must be placed in the backend/out directory.

Build Script Implementation

Your build script (Makefile, shell script, etc.) must explicitly ensure binaries are moved to backend/out. If they are not, the CI will fail to include them in the final distribution.

Example Makefile snippet:

hello:
	mkdir -p ./out
	gcc -o ./out/hello ./src/main.c

Note: While local builds might use a top-level out folder, the distribution process expects the backend/out structure described above.

You can start a new project by forking this repository or using the GitHub "Use this template" button.

Initial Setup

In your local repository, run the following to install dependencies and build the frontend for testing:

1. pnpm i
2. pnpm run build

Development Workflow

• Frontend Changes: Every time you modify frontend files (e.g., index.tsx), you must rebuild the project using pnpm run build or the build task in your IDE.
• IDE Integration: If using VSCodium or VSCode, you can simply run the setup and build tasks provided by the workspace.
• Updating Libraries: If you encounter build errors caused by an outdated library, update the UI library using:

pnpm update @decky/ui --latest

Reference Material

For UI components and implementation details, consult the decky-frontend-lib repository. Note that development should primarily target Steam Deck hardware.

Plugins can be distributed via the decky-plugin-database or as a .zip file for manual installation via decky-loader.

Required Plugin Zip Layout

A valid distribution zip must follow this structure:

pluginname-v1.0.0.zip
   |-- pluginname/ (directory)
   |      |-- bin/ (optional directory)
   |      |      |-- binary (optional)
   |      |-- dist/ (required directory)
   |      |      |-- index.js (required)
   |      |-- package.json (required)
   |      |-- plugin.json (required)
   |      |-- main.py (required if using python backend/serverAPI)
   |      |-- README.md (optional)
   |      |-- LICENSE(.md) (required)

Licensing Requirements

• A LICENSE file is required in the root of your repository.
• If your license requires the license text to be included with the source/binaries, it must be present in the zip.
• Standard Procedure: Place your chosen license at the top of the file and keep the original plugin-template license at the bottom. Failure to do this may result in rejection from the plugin database.

During the _migration() phase, use the following decky utility functions to move legacy data to the appropriate Decky-managed directories:

• decky.migrate_logs(old_path): Migrates a log file to decky.decky_LOG_DIR.
• decky.migrate_settings(old_file_path, old_dir_path): Migrates settings files or entire directories to decky.decky_SETTINGS_DIR.
• decky.migrate_runtime(old_dir_path_1, old_dir_path_2): Migrates runtime data directories to decky.decky_RUNTIME_DIR.

async def _migration(self):
    # Example: Migrating logs
    decky.migrate_logs(os.path.join(decky.DECKY_USER_HOME, ".config", "template.log"))
    
    # Example: Migrating settings
    decky.migrate_settings(
        os.path.join(decky.DECKY_HOME, "settings", "template.json"),
        os.path.join(decky.DECKY_USER_HOME, ".config", "template")
    )
    
    # Example: Migrating runtime data
    decky.migrate_runtime(
        os.path.join(decky.DECKY_HOME, "template"),
        os.path.join(decky.DECKY_USER_HOME, ".local", "share", "template")
    )

The definePlugin function from @decky/api is the entrypoint for your frontend plugin. It accepts a callback function that returns a plugin configuration object. This configuration object defines how your plugin appears and behaves in the Decky UI.

Plugin Configuration Object Properties:

• name: The name shown in various Decky menus.
• titleView: A React element displayed at the top of your plugin's menu (often using staticClasses.Title).
• content: The main React component/element that renders the plugin's menu content.
• icon: The icon displayed in the plugin list (e.g., a React Icon component).
• onDismount: A lifecycle function triggered when the plugin is unloaded. Use this to clean up event listeners or routes.

export default definePlugin(() => {
  return {
    name: "Test Plugin",
    titleView: <div className={staticClasses.Title}>Decky Example Plugin</div>,
    content: <Content />,
    icon: <FaShip />,
    onDismount() {
      // Cleanup logic here
    },
  };
});

The Plugin class uses specific underscored methods to manage the plugin lifecycle. These are called automatically by the Decky loader at different stages:

• _migration(): Executed before _main(). Use this to move old configuration, logs, or runtime data to the new standard Decky directories.
• _main(): The primary entrypoint. This is where you initialize your plugin, start background tasks, and perform setup logic.
• _unload(): Called when the plugin is being stopped (e.g., the user disables it), but before it is completely removed. Use this to gracefully stop services.
• _uninstall(): Called after _unload during a full uninstallation. Use this to clean up processes or files that should not remain on the system.

class Plugin:
    async def _migration(self):
        # Perform migrations here
        pass

    async def _main(self):
        # Main plugin logic
        pass

    async def _unload(self):
        # Handle stopping the plugin
        pass

    async def _uninstall(self):
        # Clean up remnants during uninstallation
        pass