How To Write A Plugin
Last updated
Was this helpful?
Last updated
Was this helpful?
Use to help you create plugins more easily
Let's create our first plugin ——
Only
package.json
andindex.js
are required
package.json
Only two fields are required by package.json
name
: package name must be a string beginning with svrx-plugin
, to help svrx
find it in npm.
engines.svrx
: Define the runnable svrx version of this plugin,svrx will automatically load the latest matching plugin engines.svrx can be a valid ,like 0.1.x
or ~0.1
index.js
Where
assets
: client resource setting,they will be automatically injected into the page
style
: css resource injection
script
: script resource injection
All resources will be merged into a single file.
hook.onCreate
: a function invoke when plugin been creating, we can control it by injected service in this example, we only use two services
logger
: logger service
config
: config service
client.js
There is a global variable named svrx
will be injected into all pages, it has some built-in services
svrx
is only accessible inside the plugin script, don't worry about global pollution
You will see Hello svrx from browser
in console panel
Unlike in server side, config in client is passed through websocket, so api is async, and return a promise
So we skip this step and try the plugin directly
Check the terminal and browser console log, we will find Hello svrx from browser
, which means plugin has worked successfully.
You can also run it in programmatical way
You can use service in two places
hooks.onCreate
plugin
event
We will explain these 7 services in turn
middleware.add(name, definition)
Usage
Param
name
[String]: A unique middleware name
in debug mode, it can be used to track the middleware call process
definition.priority
[Number]: default is 10
. Svrx will assemble the middleware according to the priority from high to low, that is, the request will be passed to the high priority plugin first.
middleware.del(name)
Delete a middleware with the specified name
Usage
Param
name
: middleware name
injector
is used for rewriting the response and inject client resources.
injector.add(type, resource)
Add a resource for injection , only js and css has been supported.
The rule as follow.
The style will be merged into /svrx/svrx-client.css
and injected before the closing head
tag
The script will be merged into /svrx/svrx-client.js
and injected before the closing body
tag
Usage
The content
will be merged into bundle script
Param
type
: Only support script
and style
resource.content
[String]: resource content
resource.filename
[String]: the path of resource file, must be a absolute path
Content has a higher priority than filename, so you can take one of them.
injector.replace(pattern, replacement)
injector.replace
will transform response body with some or all matches of a pattern replaced by a replacement.
Usage
The above example replace all svrx
with server-x
Param
pattern
[String|RegExp]
replacement
[String|Function]
resource injection is based upon
injector.replace
Built-in event listener, support async&sorted emitter, , which can call the listen function in turn, and can terminate the event delivery at any time.
events.on(type, fn)
Usage
Param
type
[String]: event name
fn(payload, ctrl)
: callback that has two params
payload
[String]: event data that pass through emit
ctrl
[Object]: control object, call ctrl.stop()
to stop 'sorted emit'
If the callback returns a
Promise
(such as async function), it will be treated as an asynchronous watcher.
events.emit(type, param, sorted)
Usage
Param
type
[String]: event name
payload
: event data
sorted
[Boolean]: default is false
, whether to pass events serially
Return
Promise
events.off(name, handler)
Remove event watcher
Usage
plugin
: triggered after plugin building.
file:change
: triggered when any file changes
ready
: triggered when server starts, if you need to handle logic after server startup (such as getting the server port), you can register this event
Config service used to modify or query the options passed by user;
config.get(path)
Get the config of this plugin.
Config is based on immutable data , you must always use config.get
to ensure getting the latest config.
Usage
if you need to get global config,just add prefix $.
Param
field
: field path,deep getter must be separated by .
, such as user.name
Return
The value of the field
config.set(field, value)
Modify the config
Usage
Param
field
: field path,deep setter must be separated by .
, such as user.name
value
: field value
config.watch(field, handler)
Listening for configuration changes, change digest will be triggered after the set
, del
, splice
method calls
Param
field
: field path,deep watcher must be separated by .
, such as user.name
handler(evt)
: watch handler
evt.affect(field)
[Function]: detect whether specific field has been changed
config.del(field)
Remove some field
Usage
config.splice(field, start[, delCount[, items...])
The Array.prototype.slice
Example
router.route(register)
Usage
Param
register({...methods}):
router.action(name, builder)
Usage
Param
name
[String]: action name
builder(payload)
payload: payload that passed to action,like 'svrx'
in above example
router.load(filename)
Also support hot reloading
Usage
Param
filename
: absolute path for routing file
Return
Promise
Logger module, who's level can be controlled by logger.level
(default is warn
)
Or cli way
Above example will output log that more than warn
, such as notify
, error
logger[level](msg)
Svrx provides multiple levels of logging: silent
, notify
, error
, warn
(default), info
, debug
Usage
logger.log
is an alias forlogger.notify
io.on( type, handler )
Param
type
: message type
handler(payload)
: handler for message
payload
: message data
io.emit(type, payload)
Send message to client
Usage
Server side
Client side
Param
type
: message type
payload
: message data
Message payload must be serializable because they are transmitted over the network
io.off(type[, handler])
Remove the message watcher
Usage
io.register(name, handler)
Register io service, which can be invoked by io.call
in client and server.
Usage
Param
name
[String]: service name used by io.call
handler
: a Function return Promise, implement service logic
io.call(name, payload)
Invoke registered service
Usage
Param
name
[String]: service name
payload
[Any]: service payload will passed to service handler
Return
Promise
The client APIs are uniformly exposed through global variable svrx
Responsible for communicating with the server
io.on(type, handler)
Listening server-side message
Usage
Server side
Client side
Note that the
io.emit()
in server-side is a broadcast and all pages will receive a message for server.
Param
type
: message type
handler(payload)
: message handler
payload
: message payload passed by io.emit
io.emit(type, payload)
Send client message to server side
Usage
Client side
Server side
Param
type
: message type
payload
: message data passed to message handler
payload
must be serializable because it is transmitted over the network.
io.off(type[, handler])
Remove io watcher
Usage
io.call(name, payload)
Usage
Param
name
[String]: service name
payload
[Any]: service payload
Return
Promise
Usage
The difference between events and io is that io is used for the communication between the server and the client, but events is a single-ended communication.
config
in client is almost identical to the server, the only difference is: the client version is asynchronous (because of network communication)
config.get(field)
Usage
if you need to get global config,just add prefix
$.
config.set
、config.splice
、config.del
The above three methods are the same as get
, which is consistent with the server, but the return value becomes Promise.
Usage
Usage
Field Details
default
[Any]: default value
required
[Boolean]: whether it is required, default is false
properties
[Object]: child fields
anyOf
: Choose one of the items, such as
It is not recommended that you publish the test plugin to npm. You can do local testing in the following ways.
After specifying the path parameter, svrx loads the local package instead of installing it from npm
configSchema
Plugin param definition based on JSON Schema ,checkout for more detail. Here we just set a user
field, it is a string
Check out setion to find out other services that available in hook.onCreate
svrx also provide other client services, please check out for help
There'll be a failure when trying to publish it by npm publish
. Because svrx-plugin-hello-world
has been published by
Further reading:
Middleware is used for adding to implement backend logic injection
Adding
definition.onRoute
[Function]: A middleware .If definition
is a function, it will automatically become definition.onRoute
The usage of injector.replace
is exactly the same as
Except for field
,params are identical to
Extending
Register route,as same as
methods: corresponding to
Register an action , like or
Return: builder must return a middleware
Load routing file manually ,Same as
io is used for the communication between server and client. Please check it out in
Listening for client messages (send by )
on the client side is exactly the same as the server, but make sure the payload is serializable** because it will be transmitted over the network
This part is exactly the same as , no retelling
Svrx config schema is based on
type
[String]: ,can be an array
,string
,number
,boolean
,object
or null
ui
: svrx extension ,whether show the config in
For further understanding, please refer to
Use Official to help you create plugins more easily