Creating Plugins

Plugins are a way for you to hook into Radonis.

Defining plugins

The following example illustrates how you can define a plugin.

import { definePlugin } from '@microeinhundert/radonis'


function yourPlugin() {
  return definePlugin({
    /**
     * The name of the plugin
     */
    name: 'your-plugin',


    /**
     * The environments the plugin is compatible with
     */
    environments: ['client', 'server'],


    /**
     * This plugin hook is called on initialization of the client
     * Environment: client
     */
    onInitClient() {},


    /**
     * This plugin hook is called before a component is hydrated
     * Environment: client
     */
    beforeHydrate() {
      return (tree) => {
        // Return modified React tree
        return tree
      }
    },


    /**
     * This plugin hook is called on boot of the server
     * Environment: server
     */
    onBootServer({ appRoot, resourcesPath }) {},
    
    /**
     * This plugin hook is called before a request
     * Environment: server
     */
    beforeRequest({ ctx }) {},


    /**
     * This plugin hook is called after a request
     * Environment: server
     */
    afterRequest({ ctx }) {},


    /**
     * This plugin hook is called before a page is rendered
     * Environment: server
     */
    beforeRender({ ctx, manifest, props }) {
      return (tree) => {
        // Return modified React tree
        return tree
      }
    },


    /**
     * This plugin hook is called after a chunk of a page has been rendered
     * Environment: server
     */
    afterRender({ ctx }) {
      return (html) => {
        // Return modified HTML
        return html
      }
    },
  })
}

Registering plugins

There are two plugin environments available: client and server. When creating plugins, the environments property declares which environments a plugin is compatible with.

Client plugins are registered inside of the client entry file resources/entry.client.ts.

// resources/entry.client.ts
import { yourPlugin } from 'your-plugin'


initClient({ plugins: [yourPlugin()] })

Server plugins are registered inside of config/radonis.ts.

// config/radonis.ts
import { yourPlugin } from 'your-plugin'


const radonisConfig: RadonisConfig = {
  /*
  |--------------------------------------------------------------------------
  | Plugins
  |--------------------------------------------------------------------------
  |
  | The registered server plugins. Client plugins are registered
  | separately inside the client entry file.
  |
  */
  plugins: [yourPlugin()],
}


export default radonisConfig

Real-world example

The following example illustrates how a plugin is created which injects a React context provider into the server-side rendering as well as the client-side hydration.

import { definePlugin } from '@microeinhundert/radonis'


export function contextProviderPlugin() {
  const contextProviderValue = {
    hello: 'world',
  }


  return definePlugin({
    name: 'context-provider-plugin',
    environments: ['client', 'server'],
    beforeHydrate() {
      return (tree) => <SomeContextProvider value={contextProviderValue}>{tree}</SomeContextProvider>
    },
    beforeRender() {
      return (tree) => <SomeContextProvider value={contextProviderValue}>{tree}</SomeContextProvider>
    },
  })
}