Plugin API#

Modern.js's Runtime Plugins allow you to extend and modify the behavior of your application during its React code execution. With Runtime Plugins, you can easily perform initialization tasks, implement React Higher-Order Component (HOC) wrapping, and more.

Plugin Structure#

A typical Runtime Plugin looks like this:

import type { RuntimePluginFuture } from '@modern-js/runtime';

const myRuntimePlugin = (): RuntimePluginFuture => ({
  name: 'my-runtime-plugin',
  setup: (api) => {
    // Use the api to register hooks
    api.onBeforeRender((context) => {
      console.log('Before rendering:', context);
    });

    api.wrapRoot((App) => {
      return (props) => (
        <MyContextProvider>
          <App {...props} />
        </MyContextProvider>
      );
    });
  },
});

export default myRuntimePlugin;

• name: A unique identifier for the plugin.
• setup: The main logic of the plugin, which receives an api object as a parameter. This api object is used to register hooks.

API Overview#

The Runtime Plugin API is primarily divided into the following categories:

• Information Retrieval: Getting runtime configuration and hook functions.
• Lifecycle Hooks: Executing custom logic at different stages of the application's rendering process.

Information Retrieval#

api.getRuntimeConfig#

Gets the runtime configuration defined by the user in the modern.runtime.ts file.

• Usage:

const config = api.getRuntimeConfig();
console.log(config.myCustomSetting);

api.getHooks#

Gets the hook functions that can be triggered manually.

• Type:

() => {
  onBeforeRender: { call: (context: any) => Promise<void> };
  // Other hooks...
};

• Usage:

const hooks = api.getHooks();
await hooks.onBeforeRender.call(myContext);

Lifecycle Hooks#

api.onBeforeRender#

Executes before the application renders (including both server-side rendering and client-side rendering). You can use this hook to perform data prefetching, modify the rendering context, etc.

• Type:

  type OnBeforeRenderFn<RuntimeContext> = (context: RuntimeContext) => Promise<void> | void;

  RuntimeContext contains contextual information about the current request, such as the request object, response object, etc.

• Usage:

  api.onBeforeRender(async (context) => {
    const data = await fetchData(context.req);
    context.data = data; // Add the data to the context
  });

api.wrapRoot#

Allows you to wrap the application's root component with a custom React component. This is commonly used to add global Providers, layout components, etc.

• Type:

  type WrapRootFn = (
    App: React.ComponentType<any>
  ) => React.ComponentType<any>;

• Usage:

  api.wrapRoot((App) => {
    const AppWrapper = (props) => {
      return (
        <MyGlobalProvider>
          <Layout>
            <App {...props} /> {/* Make sure to pass props */}
          </Layout>
        </MyGlobalProvider>
      );
    };
    return AppWrapper;
  });

Advanced Usage#

Combining Hooks#

You can combine multiple hooks to implement more complex functionality. For example, you can use onBeforeRender to fetch data and then use wrapRoot to pass the data to the entire application via Context:

import { RuntimePluginFuture, RuntimeReactContext } from '@modern-js/runtime';
import { useContext, createContext } from 'react';

export const ThemeContext = createContext<{ theme: string } | null>(null);

export const themePlugin = (): RuntimePluginFuture => {
  return {
    name: 'theme-plugin',
    setup: api => {
      api.onBeforeRender(async context => {
        const userPreference = await fetch('/api/user/theme-settings').then(
          res => res.json(),
        );
        context.data = {
          theme: userPreference.theme,
        };
      });

      api.wrapRoot(App => {
        return props => {
          const context = useContext(RuntimeReactContext);
          return (
            <ThemeContext.Provider value={context.data}>
              <App {...props} />
            </ThemeContext.Provider>
          );
        };
      });
    },
  };
};