Runtime Plugin API
Plugin hook definition:
export interface FarmRuntimePlugin {
// plugin name
name: string;
// invoked when the module system is bootstrapped
bootstrap?: (moduleSystem: ModuleSystem) => void | Promise<void>;
// invoked after new module instances are created
moduleCreated?: (module: Module) => void | Promise<void>;
// invoked after module initialization functions are called
moduleInitialized?: (module: Module) => void | Promise<void>;
// invoked after module caches are read, return true to skip cache reading
readModuleCache?: (module: Module) => boolean | Promise<boolean>;
// called when module is not found
moduleNotFound?: (moduleId: string) => void | Promise<void>;
// called when loading resources, custom your resource loading in this hook.
// return { success: true } to indicate that this resources have been loaded successfully.
// return { success: false, retryWithDefaultResourceLoader: true } to indicate that this resources have not been loaded successfully and should be retried with the default resource loader.
loadResource?: (
resource: Resource,
targetEnv: 'browser' | 'node'
) => Promise<ResourceLoadResult>;
}
Writing Runtime Plugin
Resource mapping and transaction recovery
moduleSystem.gd() returns a detached mapping snapshot; sd(resources, moduleResources) restores that mapping. These operations do not undo executed JavaScript or arbitrary plugin side effects.
await moduleSystem.beginResourceTransaction() drains prior imports before opening a resource batch. The batch supports asynchronous validate() followed by synchronous finalize(), or the convenience commit(). New tracked work or mapping changes invalidate readiness. On failure, rollback() drains outstanding requests and restores the batch's resource state; coordinate module factories, caches and plugin recovery separately. Only one resource transaction may be open at a time.
The HMR API import.meta.hot.registerUpdateParticipant(prepare) can coordinate a participant with validate, optional ready, synchronous commit, rollback and recover callbacks. All fallible asynchronous checks belong in validation, not finalization. Rollback is not a deep copy of module exports or a reversal of arbitrary side effects.
Hooks
Then are 2 kind of execution orders when calling Farm runtime plugin hooks:
serial: The hook is called one by one by the order of plugins. All plugins would be called serially.first: Skip all left plugins oncetruthyvalue is returned.
name
type:string
The name of your runtime plugin.
bootstrap
hook type:serialtype:(moduleSystem: ModuleSystem) => void | Promise<void>
Invoked once when the module system is bootstrapped. Setup your plugin in this hook. Example:
export default <Plugin>{
name: 'farm-runtime-hmr-client-plugin',
// define hooks
bootstrap(moduleSystem) {
hmrClient = new HmrClient(moduleSystem);
hmrClient.connect();
},
};
moduleCreated
hook type:serialtype:(module: Module) => void | Promise<void>
Invoked after new module instances are created. You can read or update property of the new created module.
export default <Plugin>{
name: 'farm-runtime-hmr-client-plugin',
moduleCreated(module) {
// create a hot context for each module
module.meta.hot = createHotContext(module.id, hmrClient);
}
};
moduleInitialized
hook type:serialtype:(module: Module) => void | Promise<void>
Invoked after module initialization functions are called.
readModuleCache
hook type:firsttype:(module: Module) => boolean | Promise<boolean>
Invoked after module caches are read, return true to skip cache reading and re-executed the module.
moduleNotFound
hook type:firsttype:(moduleId: string) => void | Promise<void>
Called when module is not registered.
loadResource
hook type:firsttype:(resource: Resource, targetEnv: 'browser' | 'node') => Promise<ResourceLoadResult>
called when loading resources, custom your resource loading in this hook.
- return
{ success: true }to indicate that this resources have been loaded successfully. - return
{ success: false, retryWithDefaultResourceLoader: true }to indicate that this resources have not been loaded successfully and should be retried with the default resource loader.
import { Plugin } from '@farmfe/runtime';
export default <Plugin>{
name: 'runtime-plugin-example',
loadResource: (resource, targetEnv) => {
// override default resource loading
// load the resource from different location
return import('./replaced.js').then(() => {
return {
success: true
};
});
}
};
Farm