Plugin Development Guide
Learn the architectural principles and best practices for building professional XyPriss plugins. This guide focuses on theoretical concepts and design patterns.
Plugin Lifecycle Flow
onServerStart blocks startup until database/resources are ready.
onServerStop ensures graceful resource disposal on shutdown.
Plugin Structure
A XyPriss plugin is a structured object implementing the XyPrissPlugin interface. It serves as a bridge between the core engine and external logic, combining metadata with lifecycle hooks and functional middleware.
Plugins are strictly typed and isolated. They must declare their identity, version, and required permissions to be accepted by the XHSC core.
Getting Started
To begin developing, you must initialize a project using XFPM and define a security contract. For a step-by-step implementation walkthrough, refer to the authoring tutorial.
Complete Authoring Tutorial
Step-by-step guide from bootstrapping with XFPM to Ed25519 cryptographic signing.
Authoring Patterns
XyPriss encourages the Plugin Factory pattern. By exporting a function that returns the plugin object, you allow users to pass configuration options during registration.
Factories should also leverage Plugin.manifest() to automatically synchronize metadata with the project's package.json, reducing maintenance overhead and preventing version drift.
Permission Discovery
The G3 architecture requires explicit permission declarations. Every hook implemented in your plugin must have a corresponding permission ID listed in your manifest.
The Plugin.inspect() utility performs a deep-scan of your plugin to identify required capabilities, ensuring you never miss a mandatory declaration.
Security Identity & Signing
Cryptographic signing is the cornerstone of plugin integrity. All G3 plugins must include a xypriss.plugin.xsig manifest signed with an Ed25519 developer key.
This process hashes every production file, ensuring that the code running in the end-user's environment is exactly what you published, free from tampering or accidental corruption.
Best Practices
Error Handling
Always handle errors in lifecycle hooks. Throwing an error in onServerStart will safely prevent the server from starting in a corrupted state.
Resource Cleanup
Use onServerStop to close database connections and flush logs. This prevents memory leaks and ensures clean process termination.
onRequest and onResponse hooks. For high-throughput servers, offload complex processing to background workers or the onServerReady hook. Explore the technical details in the and .Explore the production-grade official plugins provided by the XyPriss core.